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PREFACE 


This manual contains a complete description of RMS-11 (Record 
Management Services for the PDP-1l) as implemented on the IAS and 
RSX-11M operating systems. Because the file and record services 
described herein apply to MACRO-11 programs, you should be familiar 
with both the RSX-11 MACRO-11 REFERENCE MANUAL and an appropriate 
PDP-11 PROCESSOR HANDBOOK. Additionally, you should read_ the 
INTRODUCTION TO RMS-1]1 MANUAL before using this manual. 


Throughout this manual, the following conventions are used in the 
description of RMS-11 macro syntax. 


1. Upper case words and letters, and punctuation marks’ other 
than those described in this preface, are written as shown. 


2. Lower case words indicate that a value is to be substituted. 
The accompanying text specifies the nature of the item to be 
substituted. 


3. Square brackets ([{]), unless used in a UIC’ specification, 
enclose optional items. 


4. An ellipsis (...) indicates that the preceding item or 
bracketed group may be repeated any number of times. 


Lastly, unless otherwise noted, decimal radix is used for numeric 
values in all examples and accompanying explanatory text. 


xi 


CHAPTER 1 


INTRODUCTION 


1.1 RMS-11 OVERVIEW 


Record Management Services for PDP-1l operating systems (RMS-11) is a 
set of routines that enables programs to process files and records 
within files. RMS-ll's variety of file organizations and _ record 
access modes gives you the ability to choose processing methods best 
suited to your application. RMS-11 files can be organized 
sequentially, relatively, or with embedded indexes. Using these file 
Organizations, you can access records in a number of ways: 


1. Sequentially. 


2. Randomly by relative record number, key value, or record's 
file address (RFA). 


3. Dynamically through a mixture of sequential and random access 
modes. 


Through control blocks allocated in your program at assembly time, you 
transmit file and record operation requests to RMS-1ll. Through these 
Same control blocks, RMS-1l returns to you the data contents of files, 
attribute information about files, and status codes. 


To utilize RMS-1ll facilities, you must understand how to: 
1. Declare the RMS-1l facilities that your program requires. 
2. Access fields in control blocks at runtime. 
3. Allocate and initialize control blocks. 


4. Perform file and record operations. 


1.1.1 Declaring RMS-11 Facilities 


Before processing an RMS-1l1 file, you must declare the RMS-11 
facilities that your program requires and allocate space in your 
program for I/0 buffers and internal RMS-11 control structures. 
RMS-11 provides a set of macros that allows you to calculate buffer 
and control structure requirements and provide for the selective 
linking of only those portions of RMS-1l actually required by your 
program. 


INTRODUCTION 


1.1.2 Accessing Fields in Control Blocks 


You communicate with RMS-11 through control blocks. Control blocks 
are formatted areas in your program. Each control block consists of 
individual data fields. At runtime, you can access control block data 
fields through special RMS-11l macros. 


1.1.3 Allocating and Initializing Control Blocks 


You must allocate space in your program for control blocks at 
assembly-time. Additionally, you can establish initial values for the 
fields in these blocks through assembly-time initialization macros. 


1.1.4 Performing File and Record Operations 


In combination with control blocks, a set of RMS-11 file and_ record 
operation macros forms the complete runtime program interface with 
RMS-11. Each such macro represents a request for a particular file or 
. record service provided by RMS-11. The fields of control blocks 
further describe the request. Using particular RMS-1l macros, you 
can: 


e Create new files 
e Process existing files 
e Extend or delete files 


e Read, write, update, or delete records within files 


1.2 ORGANIZATION OF INFORMATION IN THIS MANUAL 


The organization of this manual corresponds to the areas discussed in 
the previous overview. However, an additional chapter is provided. 
Chapter 2 provides an overview of the program interface with RMS-1l, 
including runtime processing macros and user control blocks and the 
interaction between these elements to produce file and record 
operations. 


Chapter 3 describes the declaration of RMS-1l facilities. It includes 
descriptions of macros that declare the use of other macros, cause the 
initialization of the RMS-1l system at runtime, declare buffer and 
control structure space requirements, and specify the processing 
environment. 


Chapter 4, on accessing control block fields at runtime, describes a 
set of general-purpose macros. These macros result in the generation 
of code that, at runtime, manipulates the contents of control block 
_ fields. 


Chapter 5 discusses the allocation of the user control block known as 
the File Access Block (FAB). This chapter further provides 
descriptions of the function of each field in the FAB and the macros 
provided by RMS-11 to initialize these fields at assembly-time. 


’ Chapter 6 describes the user control block known as the Record Access 
Block (RAB). 
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Chapter 7 details control blocks known as Extended Attribute Blocks 
(XABs). 


Chapter 8 discusses the Name Block (NAM). 


Chapter 9 details file and record operations. In addition to 
describing the macros that cause these operations, this chapter also 
discusses establishing and terminating a record access stream, the 
current context of record operations, file sharing, synchronous and 
asynchronous operations, and record transfer modes. 


Additionally, a number of appendixes provide detailed information of 
further interest. Appendix A lists the status codes returned by 
RMS-11. Appendix B describes block I/O, a facility that allows your 
program to bypass entirely the record processing capabilities of 
RMS-11. Appendix C summarizes the handling of ANSI-labeled magnetic 
tapes. 


Appendix D contains formulas enabling you to calculate the data 
capacities of RMS-11 files. Sample code segments demonstrating the 
program interface to RMS-11 are shown in Appendix E. 


Finally, Appendix F summarizes the steps you must take to assembly and 
task build programs that use RMS-1l1 facilities. 


CHAPTER 2 


THE PROGRAM INTERFACE WITH RMS-11 


To obtain RMS-1ll services at runtime, your program must’ contain 
processing macros and user control blocks. This chapter introduces 
these macros and control blockS and summarizes their role in the 
processing of RMS-11 files. Subsequent chapters expand this 
introductory material and provide the detailed information necessary 
to write programs that use RMS-1l facilities. 


RMS-11 processing macros are expanded at assembly-time. The resulting 
code is executed at runtime to perform the desired operation. Each 
Macro represents a program request for a file or record related 
service. 


With every request for a service, information is exchanged between 
your program and RMS-1l1l. User control blocks are the means by which 
this exchange occurs. Prior to issuing a request for an RMS-11 
service, your program must place information detailing the request in 
a control block. For example, a request to open a file must _ be 
accompanied by the name of the file, information on how the file will 
be accessed, and details on how the file is to be Shared. As another 
example, a program request to read a record from a file must specify 
an access mode and, if appropriate, a key value identifying the 
desired record. ; 


After a request for service has been processed, RMS-1ll uses the same 
control block to return information to your program. When a file has 
been successfully opened, RMS-11l provides attribute information such 
as the organization of the file and the format of the records in the 
file. After successfully obtaining a record from a file, RMS-1l 
provides your program with the location in memory and length of the 
record retrieved. 


The amount of information exchanged between RMS-11 and your’. program 
varies with the nature of the request and the attributes of the file 
being processed. Detailed information on the input to and output from 
each type of runtime processing macro is provided in Chapter 9 of this 
Manual. This current chapter emphasizes only the general interface 
used by a program when requesting RMS-1l services. This interface is 
described in three sections: 


e Runtime processing macros 
e User control blocks 


e File and record operations 
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Table 2-3 
User Control Blocks 


File Access Block (FAB) Describes a file and contains 
file-related information. 


Record Access Block (RAB) Describes a record and 
contains record-related 
information. 


Extended Attribute Blocks (XABs) Contain file attribute 


information beyond that in the 
FAB. 


Name Block (NAM) Describes a location 
containing the expanded file 
specification resulting from 
the application of default 
values to a primary name 
string. 


The subsections that follow describe each control block listed in 
Table 2-3. 


2.2.1 The File Access Block (FAB) 
At runtime, a File Access Block (FAB) represents a particular file. 
The fields of the FAB are used to contain such file-related 
information as: 

e The name of file 

6 The organization of the file 

e The operations your program will perform on the file 

e The format of records within the file 


e Record size information 


e Allocation information 


2.2.2 The Record Access Block (RAB) 


A Record Access Block (RAB) iS needed whenever individual records ina 
file are to be accessed. 


A RAB describes an individual record. It iS used to communicate 
information about that record between your program and RMS-ll. Once a 
file has been opened, you will use the fields of the RAB to describe a 
record to be accessed. 
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2.2.3 Extended Attribute Blocks (XABs) 


There are several types of Extended Attribute Blocks (XABs). Each 
type contains fields that represent one attribute of a file. These 
attributes supplement those attributes in a File Access’ Block. 
Specifically, there are Extended Attribute Blocks that describe: 


e File creation and revision dates 
® Primary and alternate key definitions for indexed files 
e File protection specification 
6 Allocation information 
You may use Extended Attribute Blocks when you: 
1. Create a new file. 


2. Request that RMS-1l transmit the extended attributes of an 
existing file to your program. 


In the first instance, your program uses XABs to pass file definition 
information to RMS-ll. In the second instance, RMS-11 requires XABs 
in order to pass attribute information to your program. 


2.2.4 The Name Block (NAM) 


A Name Block (NAM) is an optional user control block. It is used _ to 
contain the full file specification resulting from the merger of 
explicit file name information with program- and system-provided 
defaults. 


2.3 FILE AND RECORD OPERATIONS 


To obtain any RMS-11 service, your program useS a combination of a 
runtime processing macro call and a user control block. The primary 
argument of every runtime processing macro, therefore, is the address 
of a user control block. 


In the following sections, the division of RMS-1l services into file 
and record operations is continued to show the relationship of runtime 
processing macros with particular user control blocks. For each type 
of operation, the relationship among control blocks is described. 


2.3.1 File Operations 


The primary argument of a file processing macro call is the address of 
a FAB. The macro call itself represents the type of file service 
requested (e.g., SOPEN, $DISPLAY, SCLOSE, etc.) and the FAB identifies 
a specific file associated with the request. The combination of macro 
call and FAB results in a file operation. 


Since each FAB represents a single file, your program must contain one 
FAB for each file that is open simultaneously. 
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You can optionally associate a Name Block (NAM) with ae FAB. This 
association involves setting the address of the NAM in a data field of 
the FAB before the file is opened. While opening the file, RMS-11 
places the results of the merger of explicit and default file 
specification information in an area described by the Name Block. 


Your program can also associate Extended Attribute Blocks (XABs) with 
a File Access Block. The presence and purpose of associated XABs are 
related to whether a new file or an existing file will be processed. 
In both instances, the presence of associated XABs is indicated by the 
address of the first such block in a data field of the FAB. When 
multiple XABs for the same file are present, they are chained together 
through address fields in the XABs themselves. 


2.3.1.1 New Files and Extended Attribute Blocks - You create a new 
RMS-11 file through a combination of the SCREATE macro call and a File 
Access Block. You will use the FAB to pass to RMS-1l a description of 
the primary attributes of the file, such as the file's organization 
and the format and size of the records the file will contain. 
However, there are no fields in a FAB that allow you to specify 
optional file attributes such as a protection specification, nor does 
the FAB allow you to define keys for an indexed file. Therefore, you 
will use XABs to pass to RMS-11l descriptions of file attributes beyond 
those contained in the FAB. 


2.3.1.2 Existing Files and Extended Attribute Blocks - Extended 
attribute blocks are never used to define or alter the attributes of 
an existing file. The attributes of a file are fixed at the time you 
create the file. Thereafter, these attributes cannot be altered. 
However, there are two occasions when XABs are associated with a FAB 
that represents an existing file: 


1. Your program contains a $DISPLAY macro. 


2. You wish automatically to obtain extended file attributes as 
additional outputs of the SOPEN macro. 


When your program issues a S$DISPLAY macro call, RMS-1l retrieves’ the 
address of an XAB from a field in the FAB associated with the call. 
This XAB may be the first of a chained list of such blocks. Further, 
each block is’ self-identifying. That is, a field in the block 
specifies the type of information the block can contain, e.g., key 
definition, file protection specification, etc. Based on the types of 
XABS present, RMS-11 obtains the specified attribute information from 
the file and stores it in the appropriate XABs. 


When your program issues an SOPEN macro call, RMS-1l examines the FAB 
associated with the call for the address of an XAB. If this block 
(possibly a chain of blocks) is present, RMS-1l automatically returns 
the appropriate attribute information into the fields of the block. 
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2.3.2 Record Operations 


The primary argument of a record processing macro (e.g., $GET, S$PUT, 
etc.) is the address of a Record Access Block. The macro call 
represents the type of record service requested and the RAB identifies 
a record associated with the request. The combination of macro call 
and RAB results in a record operation. 


Once a file has been opened by a SOPEN or SCREATE file operation, your 
program must activate a record access stream before performing record 
operations. After a record access stream has been activated, your 
program can specify a record for access through the use of three 
RMS-1ll access modes. The following subsections, therefore, describe: 


e Record access streams 


e Specifying a record for access 


2.3.2.1 Record Access Streams - A record access stream is the 
association of a RAB with a FAB. This association occurs through the 
issuance of a $CONNECT macro call. Once this association has_ been 
established, your program can process records in the file represented 
by the FAB. When processing a relative or indexed file, you can 
associate more than one RAB with the same FAB. Each association 
represents an independent record access stream to the same file. For 
example, your program could access records within an indexed file by 
primary key while, through a second record access stream, acceSsing 
records within the same file through the index associated with an 
alternate key. 


At any point in time, a particular RAB can be associated with only a 
Single FAB. The number of RABS required by a program, therefore, 
depends on the maximum number of record acceSS streams active 
Simultaneously. 


2.3.2.2 Specifying a Record for Access - The organization of a file 
establishes the techniques (called access modes) that can be used to 
specify records for access. The organization of a file is fixed at 
the time the file is created. The access mode used to process records 
in a file, however, can be different each time the file is opened. 
Further, your program can dynamically switch from one access mode to 
another during the runtime processing of a file. 


RMS-11 supports three record access modes: 
1. Sequential 
2. Random 
3. Record's File Address (RFA) 


The following subsections describe each access mode. 


2.3.2.2.1 Sequential Access Mode - When using sequential access mode, 
your program iSsues a series of requests for the next record. RMS-11l 
interprets these requests in the context of the organization of the 
file being processed. Thus, the order in which records are read or 
written is governed by the structure, or organization, of the file. 
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2.3.2.2.2 Random Access Mode - In random access mode, your program, 
rather than the organization of the file being accessed, determines 
the order in which records are processed. Each program request for a 
record specifies, through fields in the RAB, the identification of the 
record of interest. Thus, when using random access mode, your program 
does not read or write the next’ record. Rather, your program 
identifies a particular record. The identifier associated with the 
request allows RMS-1l to locate the record within the file. The 
random access mode cannot be used with sequentially organized files. 
Both the relative and indexed file organizations, however, permit 
random access to records. 


2.3.2.2.3 Record's File Address (RFA) Access Mode - Record's’ file 
address (RFA) access mode is similar to random access mode in that it 
allows a specific record to be identified for retrieval. It can be 
used with any file organization so long as the file resides on a disk 
device. It cannot, however, be used for write operations. 


The term record's file address is meant to convey the notion that 
every record within a file has a unique address. The actual format of 
this address depends on the organization of the file. In all 
instances, however, only RMS-1l can interpret this format. 


The most important feature of record's file address access is that the 
RFA of any record remains constant while the record exists in the 
file. After every successful $GET, $PUT, or S$FIND operation, the RFA 
of the desired record is returned by RMS-ll ina field of the Record 
Access Block associated with the operation. Your program can then 
save this RFA to be used again later to retrieve the same record. It 
is not required that an RFA be used for subsequent retrieval only 
during the current execution of the program. During a file's 
existence, RFA's can be used at any subSequent point in time. 


CHAPTER 3 


DECLARING RMS-11 FACILITIES 


Every program that processes RMS-11 files must contain directives and 
special-purpose macros that declare the RMS-1l facilities required at 
assembly-time and at runtime. This chapter describes these directives 
and macros. 


To declare RMS-1ll1 facilities that are used by your program, you must 
do the following: 


1. List RMS-11 macros in .MCALL directives. 
2. Declare the processing environment. 

3. Declare space pool requirements. 

4. Issue an $INIT or an S$INITIF macro. 


The sections of this chapter describe each of these requirements. 


NOTE 


Unless otherwise noted, RMS-1ll macros 
use decimal as the default radix for 
numeric values. 


3.1 .MCALL DIRECTIVE - LISTING NAMES OF REQUIRED MACRO DEFINITIONS 


All macro calls issued in your program must be listed as arguments’ in 
an .MCALL directive. Listing the macro calls in this way allows the 
corresponding macro definitions to be read in from macro libraries 
during assembly. 


Each .MCALL directive takes the following form: 
-«MCALL argl,arg2,...,argn 
where 
argl,etc. represents a list of symbolic names of the macro 
definitions required in the assembly of the 
program. Macro names may be listed in any order. 
The number of .MCALL directives needed for RMS-11 macros can _ be 
minimized. Table 3-1 lists a set of macro names. The definitions in 
the system macro library for most of these macros contain embedded 


-MCALL directives. These embedded .MCALL directives list as arguments 
the names of additional RMS-11 macros. Thus, by providing .MCALL 
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directives with the names of the macros in Table 3-1, you effectively 
can provide .MCALL directives for any and all RMS-1l macros used in a 
program. 


Table 3-1 
Minimum Set of .MCALL Directives 


User Supplied 
-MCALL Argument Embedded .~.MCALL Arguments 


ORGS (none) 


POOLSB Space pool declaration macros (described in 
Section 3.3). 


SINIT or SINITIF (none) 


SGNCAL Runtime field manipulation macros (described 
in Chapter 4) and completion routine macros 
(described in Chapter 9). 


File Access Block allocation and 
initialization macros (described in Chapter 
5). 


Record Access Block allocation and 
initialization macros (described in Chapter 
6). 


Extended Attribute Block allocation and 


initialization macros (described in Chapter 
ver 


NAMSB Name Block allocation and initialization 
macros (described in Chapter 8). 


SFBCAL File processing macros (described in Chapter 
9). 


SRBCAL Record processing macros (described in 
Chapter 9). 


As shown in Table 3-1, you can ensure that all RMS-11 macros used ina 
program appear aS arguments in .MCALL directives by coding the 
following sequence of .MCALL directives and macro calls. 


-MCALL ORGS$,POOLSB,SINIT 

-MCALL S$GNCAL,FABSB, RABSB, XABS$B,NAMSB 
-MCALL SFBCAL,$RBCAL 

SGNCAL 

SFBCAL 

$RBCAL 


In the preceding example, the $GNCAL, $FBCAL and $RBCAL macro calls 
are issued after being listed in .MCALL directives. By issuing these 
macro calls, you will cause the embedded .MCALL directives to take 
effect. Naturally, you can omit any macro names from .MCALL 
directives that do not apply to a particular program. If Name Blocks 
or Extended Attribute Blocks are not used, for example, there would be 
no need for listing the NAM$B or XABSB_ macros. Further, you may 
choose not to use the $RBCAL or $FBCAL macros, for example, but rather 
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to list separately each record processing and file processing macro 
actually appearing in your program. 


3.2 ORG$ - DECLARING THE PROCESSING ENVIRONMENT 


You must include one or more ORGS macros within the set of modules 
that you will link together through the Task Builder to produce an 
executable task. 


NOTE 


All ORGS macros must be in modules’7 that 
are part of the root of your task. An 
ORG$ macro for a particular file 
organization must be present even if no 
record operations are performed when 
such a file is opened. 


The presence of ORGS macros in your source modules allows the Task 
Builder to select for linking only those portions of RMS-11l actually 
required by your program. Each ORG$ macro declares a unique 
combination of file organization and record operations. 


The ORGS$ macro takes the following form: 


ORGS org[,<recop[,recop...]>] 


where 
org is the type of file organization to be processed. 
One of the following symbolic values’ must be 
specified: 
IDX - indexed file organization 
REL - relative file organization 
SEQ - sequential file organization 
recop is a symbolic value identifying a type of 
operation that will be performed on a file of the 
specified organization. If a single value is 


specified, the angle brackets are not needed. If 
multiple values are specified, you must’ enclose 
them in angle brackets and use commas to separate 
each value from the preceding value. One or more 
of the following may be specified in any order: 


CRE - indicates a file of the specified 
organization may be created 


DEL - indicates $DELETE operations 
FIN - indicates $FIND operations 
GET - indicates SGET operations 
PUT - indicates $PUT operations 


UPD - indicates SUPDATE operations 
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The following is an example of the use of ORGS macros in a_- source 
module: 


ORGS SEQ,<CRE,PUT> 
ORGS IDX,<GET,UPD,FIN> 
ORGS REL 


In this example, the user declares that one or more sequential files 
will be created and $PUT operations performed. One or more indexed 
files will be opened and S$GET, $UPDATE, and $FIND operations will be 
performed on such files. Finally, one or more relative files will be 
opened but no record operations will be performed (possibly such files 
will be opened only for the purpose of issuing an S$EXTEND or S$DISPLAY 
file operation). 


3.3 DECLARING SPACE POOL REQUIREMENTS 


RMS-11 requires a collection of I/0 buffers and internal control 
structures to support file procesSing at runtime. The area in your 
program occupied by these buffers and control structures is known as 
the space pool. RMS-1l provides facilities that ensure that the space 
pool is large enough to accommodate only the requirements of the 
largest number of files that can be open simultaneously. By using 
these facilities at assembly-time, your program provides information 
that allows RMS-11 to calculate the minimum size requirements of the 
space pool. 


The major portion of the space pool is composed of I/0 buffers. To 
the user program, record processing under RMS-1l appears as the 
movement of records directly between a file and the program itself. 
Transparent to the user program, however, RMS-11 actually reads and 
writes either virtual blocks or buckets into I/O buffers. When the 
Organization of a particular file is sequential, RMS-11 reads or 
writes virtual blocks. For relative and indexed files, RMS-1l_ reads 
or writes buckets. 


The size of I/O buffers depends on the organizations of the files 
being processed, the number of files open simultaneously, and the 
number of simultaneously active record access streams. In providing 
the information needed to calculate the size requirements for the I/O 
buffers portion of the space pool, you have two choices: 


1. A completely centralized space pool. 
2. Private I/O buffers for one or more files. 


In a completely centralized space pool, all I/0 buffers as well as the 
internal control structures required for file processing are 
inaccessible to your program. RMS-11 totally manages the space within 
the pool and allocates portions, as needed, for buffer space and 
control structures for open files. 


Unlike a completely centralized space pool, the use of private I/0 
buffers allows you some measure of control over I/O buffer space. You 
can allocate private I/O buffers on a per-file basis by specifying the 
address and total size of these buffers in fields of the File Access 
Block associated with a file. When the file is open, this’ buffer 
space is completely managed by RMS-11 and your program must not access 
it. However, when the file is closed, the private I/O buffer space is 
available for use by your program. 
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The major advantage of private I/O buffers is avoidance of 
fragmentation of a completely centralized space pool. Since 
particular files have varying buffer requirements baSed on their 
organization, a centralized space pool can reach the point where there 
is sufficient total space available for the opening of an additional 
file but the space is not contiguous. When such a situation arises, 
the desired file cannot be opened. 


Whether you choose a completely centralized space pool or private I/O 
buffers, RMS-1l always requires certain internal control structures 
that must be allocated in the space pool to support file processing. 
Unlike the handling of I/O buffers, your program can never access 
these control structures or recover the space they occupy. 


The number of internal control structures required by RMS-1l1l in the 
space pool is based on the organizations of the files being processed, 
the maximum number of files open simultaneously, and the maximum 
number of simultaneously connected record access streams. Once again, 
your program must provide, at assembly-time, the information needed to 
determine the size requirements of the internal control structures 
that must be allocated in the space pool. 


The presence in your source modules of the macros listed in Table 3-2 
allows RMS-1l to determine the size requirements for your program's 
Space pool. The descriptions following the table identify those 
Macros that are always required and those that are needed only in 
specific instances. If you want private I/O buffers for one or more 
files, you must also refer to the descriptions of the BPA (buffer pool 
address) and BPS (buffer pool size) fields in Chapter 5. 


Table 3-2 
Space Pool Declaration Macros 


Macro Description 


POOLSB | Beginning of space pool declaration 


PSBDB Number of buffer descriptor blocks 


PSFAB Number of files open simultaneously 


PSRAB Non-indexed record access streams active 
simultaneously 


PSRABX Indexed record access streams active simultaneously 
PSIDX Number of defined keys 
PSBUF Input/output buffer requirements 


POOLSE End of space pool declaration 


3.3.1 POOLSB/POOLSE - Space Pool Declaration 


The POOLSB macro is required. It marks the beginning of a sequence of 
space pool definition macros. This macro takes the form: 


POOLSB 
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The POOLSE macro is also required. It marks the end of a sequence of 
space pool declaration macros. It takes the form: 


POOLSE 


The remaining macros listed in Table 3-2 can be coded in any order 
following the POOLS$B macro and before the POOLSE macro. Multiple 
instances of such space pool declarations can occur among the set of 
source modules that you will link together through the use of the Task 
Builder. The Task Builder will sum the size requirements indicated by 
all such space pool declarations. 


3.3.2 PSBDB - Number of Buffer Descriptor Blocks 


The PSBDB macro iS required. It ensures that the space pool contains 
sufficient space for internal RMS-11 control structures known as 
buffer descriptor blocks. 


The format of this macro is: 
PSBDB bdbnum 
where 


bdbnum is a numeric value or symbol representing the 
number of buffer descriptor blocks required to 
Support the file processing performed by your 
program. To determine this value, you must apply 
the following formula: 


bdbnum = maxbuf + maxrel + (2 * maxidx) 
where 


maxbuf is the maximum number of I/O buffers ever in use 
for simultaneously open files. You calculate this 
value by totaling the multi-buffer counts in the 
MBF fields of RABs for all combinations of 
Simultaneously connected record access’ streams. 
The maximum value among all such combinations is 
the desired maxbuf value. 


maxrel is the maximum number of record access’ streams 
ever connected simultaneously for write operations 
to relative files (whether or not an actual write 
operation is performed). 


maxidx is the maximum number of record access streams 
ever active simultaneously for write operations to 
indexed files (whether or not an actual write 
operation is performed). 


3.3.3 PSFAB - Number of Files Open Simultaneously 

The PSFAB macro iS required. It ensures that there will be sufficient 
storage in the space pool for internal RMS-11 control structures 
related to File Access Blocks. The format of this macro is: 


PSFAB number 
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where 
number is a numeric value representing the maximum number 
of files that can be open simultaneously at run 
time. 


An example of the PS$FAB macro follows: 


POOLS$B 


PSFAB 4 


POOLSE 


In this example, the user specifies that a maximum of four files’ can 
be open simultaneously at run-time. 


3.3.4 PSRAB - Non-indexed Record Access Streams 


The PSRAB macro ensures that there will be sufficient storage in the 
space pool to accommodate internal control structures related to 
Record Access Blocks for relative or sequential files. This macro can 
be omitted, therefore, if no record operations are performed on 
relative or sequential files. 


The format of the PS$RAB macro is as follows: 
-PSRAB rabs 
where 
rabs is a numeric value representing the maximum number 
of Record Access Blocks’ that will be connected 
simultaneously for relative and sequential files. 
In the following example, the user declares that a maximum of three 
Record Access Blocks, representing access streams to non-indexed 


files, will be connected simultaneously. 


POOLSB 


POOLSE 


3.3.5 PSRABX ~- Indexed Record Access Streams 


The PSRABX macro ensures that there will be room in the space pool for 
internal RMS-l1l control structures related to indexed files. This 
macro is required, therefore, if the program accesses records in any 
indexed file. The format of this macro is as follows: 


PSRABX rabs,ksize,ckeys 
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where 

rabs is a numeric value representing the maximum number 
of Record Access Blocks’ that will be connected 
Simultaneously for indexed files. 

ksize is a numeric value representing the size (in 
bytes) of the largest key field within all the 
files represented by the first argument. 

ckeys is a numeric value representing the number of keys 


that can change when a SUPDATE operation is 
performed on an indexed file. This value must be 
specified whenever an indexed file is accessed for 
SUPDATE operations (i.e., the FAC field in the FAB 
for the associated file contains FBSUPD), whether 
or not a $UPDATE is actually performed. 


The following is an example of the PSRABX macro: 


POOLSB 


PSRABX 1,32 


POOLSE 


In this example, the user specifies that there will be at most a 
single Record Access Block connected for processing an indexed file at 
any point during program execution. The size of the largest key field 
in any such file is 32 bytes and no keys can change during a SUPDATE 
operation. 


3.3.6 PS$IDX - Number of Defined Keys 


The PSIDX macro reserves storage in the space pool for’ control 
structures containing internal key summary information. This macro is 
required if any indexed file is accessed by your program. Its format 
is as follows: 


PSIDX keys 
where 
keys is a numeric value representing the total number 
of all keys defined for all indexed files opened 
Simultaneously. This total must be specified even 


if certain keys within one or more files are never 
used for retrieval operations. 


The following is an example of the PSIDX macro: 
POOLSB 


PSIDX 3 


POOLSE 
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In this example, the user declares that a total of three keys are 
defined among all indexed files that are open simultaneously. 


3.3.7 PS$BUF - I/O Buffers 


The PSBUF macro ensures that the space pool is large enough for I/0 
buffers required to support the file and record processing performed 
by your program. If you choose to allocate private I/O buffers’ for 
all files, this macro can be omitted. If, however, one or more files 
will be processed without associated private I/O buffers, this macro 
is required. 


The amount of buffer space required depends on the following: 


e The maximum number of simultaneously active record access 
streams. 


@ The bucket size or block size of the file associated with 
each stream. 


e The multi-block count (MBC) specified in the Record Access 
Blocks representing streams connected to disk sequential 
files. 


e The multi-buffer count (MBF) specified in each Record Access 
Block representing each stream. 


To calculate buffer space requirements, you employ the following 
formula: 


buffsize = stmsizel[+stmsize2...+stmsizen] 


where 
stmsizel, are the I/O buffer space requirements (in bytes) 
stmsize2, for each Simultaneously active record access 
etc. stream associated with a file without private I/0 


buffers. The requirements of each such stream are 
determined as follows: 


FOR DISK FILES 
stmsize=BKS* (512*MBC) *MBF 
where 
BKS is the number of virtual blocks in the 
largest size bucket of the file 
associated with the stream. For 


sequential files, BKS equals 1 in this 
formula. 
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MBC is the value contained in the 
multi-block count (MBC) field of the 
Record Access Block associated with 
the stream. This value is used only 
with sequential files. For 
non-sequential files, MBC equals 1 in 
this formula. 


MBF is the value contained in the 
multi-buffer count (MBF) field of the 
Record Access Block associated with 
the stream. 

FOR MAGNETIC TAPE FILES 


stream-size=BLS*MBF 


where 
BLS is the size (in bytes) of each 
physical block of the file associated 
with the stream. The default block 
size for magnetic tape files is 512 
bytes. 
MBF is the value contained in the 


multi-buffer count (MBF) field of the 
Record Access Block associated with 
the stream. 


The format of the PSBUF macro is as follows: 
PSBUF buffsize 
where 


buffsize is a numeric value representing the total size (in 
bytes) of the I/O buffers required to support 
files without private I/O buffers. The specified 
value must be a multiple of 4. 


In the following example of the PSBUF macro, the user specifies that a 
total of 8192 bytes of I/O buffer space is required: 


POOLSB 


PSBUF 8192 


POOLSE 


3.4 $INIT OR SINITIF — INITIALIZING THE RMS-11 SYSTEM 


You must include either an SINIT or an “SINITIF macro in the 
initialization code of any program that uses RMS-1l facilities. When 
encountered at runtime, the SINIT macro call attempts the 
initialization of the RMS-1ll_ system. The SINITIF macro performs 
initialization if RMS-1l is not presently initialized. RMS-11 uses 
the C-Bit of the Processor Status Word to indicate success or failure 
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initialization procedure. If the C-Bit is cleared, 


initialization was successful. 


The formats of these macros are: 


where 


1. 


label: SINIT 


2. label:SINITIF 


label 


is an optional user-specified symbol that allows 
control to be transferred to this location during 
program execution. Other instructions in the 
program may refer to this label, as in the case of 
a program that has been written so that it can be 
restarted. 


NOTE 


The SINIT macro will not cause 


initialization if any files are open. 


CHAPTER 4 


ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME 


This chapter describes RMS-1l runtime macros that retrieve, modify, 
and test the contents of data fields in user control blocks. 


Runtime field access macros expand into code that affects the contents 
of data fields during execution of your program. Using one or more of 
these macros, you can perform any of the following actions during 
program execution: 


e Store values into control block data fields before the 
control block is used for the first time. You will perform 
this action frequently since there are no runtime defaults 
for any fields in control blocks. 


e Alter the contents of a control block data field to suit the 
logic of your program, e.g., dynamically changing the access 
mode used to process a file from random to sequential. 


e Test or compare the contents of control block data fields 
returned by RMS-1l to your program, e.g., the status field 
(STS) of a Record Access Block or File Access Block. 


The runtime macros that perform the preceding functions are listed in 
Table 4-1. RMS-11 limits all but two of these macros to use with l 
byte or 1 word fields. The following table, therefore, also includes 
the size of control block data fields that can be accessed by the 
specified macro. 


Table 4-1 
Runtime Field Access Macros 


SCOMPARE 1 byte or 1 word Compares the contents of a field 
with a user-specified value. 


SFETCH Any size Copies the contents of a field into 
a user-specified location. 


SOFF l byte or 1 word Resets one or more bits within a 
bit string field. 


SSET 1 byte or 1 word Sets one or more bits within a bit 
string field. 


SSTORE Any size Changes the contents of a field. 


STESTBITS 1 byte or 1 word Tests one or more bits within a 
field. 
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The macros in Table 4-1 are provided so that you need not be aware of 
the specific placement (and, to a large extent, size) of the fields 
within RMS-1l control blocks. The placement of these fields may 
differ from release to release. There are instances, however, when 
knowledge of placement is desirable (e.g., during debugging). This 
information can be derived from the symbol table of an assembly 
listing file of any module containing the control block(s) of 
interest. Offset values are represented by symbols beginning with the 
two characters 'O$'. For one-word and one-byte fields, the offset 
symbol is simply the concatenation of 'O$' with the three-character 
field name. For example, OSSTS represents the offset (in bytes) of 
the STS field from the beginning of a FAB or RAB. For multi-word 
fields (such as ALQ in the FAB or in an allocation XAB) and multi-byte 
fields (such as SIZ in the key definition XAB), each word (or byte) is 
represented by an offset symbol that is the concatenation of 'OS$', 
plus the 3-character field name, plus a digit in the range 0 ton, 
where n is 1 less than the number of words (or bytes) in the field. 
For example, the ALQ field is represented by the offset symbols OSALQO 
(the less significant word) and OSALQ1 (the more significant word); 
the SIZ field is represented by the symbols O$SIZ0 (the size of the 
first, most Significant, key segment), OSSIZ1, ..., OSSIZ7 (the size 
of the last, least significant, key segment). 


The sections that follow describe each of the macros listed in Table 
4-1. The 3-character names of fields in control blocks and the 
symbolic values that can be used to test and set these fields are 
specified in Chapters 5 through 8. 


NOTES 


l. Octal radix iS assumed for all numeric 
values used aS operands in the macros 
described in this’ chapter. You can 
indicate decimal radix through the use 
of an explicit decimal point following a 
numeric value. 


2. In all instances in which a_e control 
block field is 2 words in length and 
contains a numeric value, the least 
significant bits appear in the first 


word of the field and the most 
significant bits in the second word. 


4.1 $COMPARE -— COMPARING THE CONTENTS OF A FIELD 


The SCOMPARE macro compares a l-byte or 1-word control block data 
field with a user-specified value and sets PDP-ll condition codes. 


The format of the SCOMPARE macro is as follows: 
label: $COMPARE source,fnm,reg 
where 


label is an optional user-specified symbol referring to 
the SCOMPARE macro. 
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source is a user-specified operand representing a value 
to be compared with the contents of a control 
block data field. You may express this operand 
using any valid addressing mode. If the operand 
is specified as #0, a TST (or TSTB) instruction is 
generated and condition codes’ set accordingly. 
The operand must be word aligned for comparison 
with l-word data fields. 


fnm is the 3-character name of a 1-byte or l-word data 
field within a user control block. The assembler 
will generate an error message if the specified 
field name represents a multi-word field. The 
user-specified source operand will be compared 
with the contents of this field. 


reg is a general register, RO through R5, loaded with 
the address of the user control block containing 
the desired data field. 


The following are examples of the SCOMPARE macro: 
SCOMPARE #SUSSUC,STS,R1 
SCOMPARE 2(R1),RSZ,R5 


In the first example, the user compares the status field (STS) of a 
control block with the symbolic value SUSSUC. The address of either a 
File Access Block or Record Access Block (both contain a status field) 
is in general register 1. In the second example, the user specifies 
that the record size field (RSZ) is to be compared with the operand 
expressed using indexed addressing mode. Since the RSZ field exists 
only in Record Access Blocks, general register R5 must contain. the 
address of a RAB. 


4.2 S$FETCH - COPYING THE CONTENTS OF A FIELD 

The $FETCH macro copies the contents of a control block data field 
into a user-specified location. This macro can be used to access any 
data field, regardless of size. 

The format of the $FETCH macro is as follows: 


label: S$FETCH destination,fnm,reg 


where 
label is an optional user-specified symbol referring to 
the S$FETCH macro. 
destination is a location within the user program into which 


the contents of a control block field are to be 
copied. The following restrictions apply to this 
operand: 


1. You cannot use immediate mode or any form of 
deferred addressing mode. 


2. If the field name specified as the second 
argument is POS or SIZ (refer to description of 
key definition XAB$ in Chapter 7), you cannot 
use register mode addressing to express the 
destination operand. 


4-3 


ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME 


3. For multi-word fields other than POS and SIZ, 
you must use care when expressing the 
destination operand with register mode 
addressing. The expanded code of the $FETCH 
macro will use successive registers as 
destination operands for successive words of 
the data field. Depending on the length of the 
data field and the register specified as the 
destination operand, this code could use the 
register containing the control block address 
as a destination operand. 


4. If the data field to be copied is one or _ more 
words in length, the specified destination 
location must be word aligned. 


£nm is the 3-character name of any data field within a 
user control block. Regardless of length, the 
contents of this field are copied to the 
user-specified location. 


The following conventions apply if the S$FETCH 
macro is used to reference the key size (SIZ) or 
key position (POS) fields of a key definition XAB 
(refer to Chapter 7 for a description of key 
definition XABs): 


e You specify the 3-character name, SIZ or POS, 
to access the entire 8-element array. The 
following example shows all eight words of the 
POS field copied into successive locations 
beginning with the user-specified destination: 


SFETCH (RO)+,POS,R3 


e To access a single element in the 8-element 
array, you specify the 3-character field name 
immediately followed by a numeric element 
number from 0 to 7. In the following example, 
the user fetches the first element of the POS 
field: 


SFETCH R4,P0S0,R3 


reg is a general register, RO through R5, loaded with 
the address of the user control block containing 
the desired data field. 


The following are examples of the S$FETCH macro: 
SFETCH R2,RBF ,R4 
SFETCH 8. (R3),MRN,R1 


In the first example, general register R4 contains the address of a 
Record Access’ Block. The user copies. the contents of the record 
address field (RBF) into general register R2. In the second example, 
general register Rl contains the address of a File Access Block. The 
user copies both words of the maximum record number field (MRN) into 
successive words beginning with the specified location. 
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4.3 SOFF - RESETTING BITS WITHIN A FIELD 


The SOFF macro resets one or more bits within 1-byte or I1-word bit 
string data fields. 


The format of the SOFF macro is as follows: 


label: SOFF value,fnm,reg 


where 

label is an optional user-specified symbol referring to 
the SOFF macro. 

value is an expression or location specifying the bits 
within the data field that are to be reset. 

fnm is the 3-character name of a l-byte or l-word data 
field within a user control block. The assembler 
will generate an error message if the specified 
field name represents a multi-word field. 

reg is a general register, RO through R5, loaded with 


the address of the user control block containing 
the desired data field. 


In the following example, general register R2 contains the address of 
a Record Access Block. The user resets the bit in the record options 
field (ROP) that specifies greater than or equal key searches. 


‘SOFF #RBSKGE,ROP,R2 


4.4 $SET - SETTING BITS WITHIN A FIELD 


The $SET macro sets one or more bits within l1l-byte or I1l-word bit 
string data fields. 


The format of the $SET macro is as follows: 


label: $SET value,fnm,reg 


where 

label is an optional user-specified symbol referring to 
the S$SET macro. 

value is an expression or location specifying the bits 
within the data field that are to be set. 

fnm is the 3-character name of a 1-byte or l-word data 
field within a user control block. The assembler 
will generate an error message if the specified 
field name represents a multi-word field. 

reg is a general register, RO through R5, loaded with 


the address of the user control block containing 
the desired data field. 


The following are examples of the $SET macro: 


SSET #FBSGET!FBSUPD ,FAC,R4 
SSET #RBSEOF ,ROP,R1 
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In the first example, general register R4 contains the address of a 
File Access’ Block. The user sets the bits within the file access 
field (FAC) that indicate SGET and SUPDATE operations will be 
performed on the associated file. In the second example, general 
register R1 contains the address of a Record Access Block. The user 
sets the bit within the record options field (ROP) that specifies 
positioning to end of file. 


4.5 $STORE - CHANGING THE CONTENTS OF A FIELD 


The $STORE macro changes the contents of an entire control block data 
field by storing values from a user-specified location. This macro 
can be used with any size data field. For multi-word fields, 
successive locations, beginning with the uSer-specified location, will 
be used as the source of values to be stored into the data field. For 
bit string data fields, the entire field will be altered. Therefore, 
if you want to change bit settings selectively in a bit string field, 
you should use the SOFF or SSET macro. 


The format of the SSTORE macro is as follows: 


label: $STORE source,fnm,reg 


where 
label is an optional user-specified symbol referring to 
the SSTORE macro. 
source is a location within the user program containing 


values to be stored into a control block data 
field. When this operand is expressed as #0, the 
expanded code of this macro will clear the entire 
data field to zero. The following restrictions 
apply to this operand: 


1. You cannot use any form of deferred 
addressing mode. 


2. Immediate mode addressing can be used only 
with l-byte or l-word fields. 


3. If the field name specified as the second 
argument is POS or SIZ (refer to 
description of key definition XABs in 
Chapter 7), you cannot use register mode 
addressing to express the source operand. 


4. For multi-word fields other than POS and 
SIZ, you must use care when expressing the 
source operand with register mode 
addressing. The expanded code of the 
SSTORE macro will use successive registers 
as source operands for successive words of 
the data field. Depending on the length of 
the data field and the register specified 
as the source operand, this code could use 
the register containing the control block 
address aS a source operand. 


5. Word alignment of source operands is 


required when setting the contents of 
fields one or more words in length. 
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fnm is the 3-character name of any data field in a 
user control block. The $STORE macro will change 
the contents of this field, regardless of its 
length. 


The following conventions apply if the SSTORE 
Macro is used to change the contents of the key 
position (POS) or key size (SIZ) fields of a key 
definition XAB (refer to description of key 
definition XABs in Chapter 7): 


e You specify the 3-character name, POS or 
SIZ, to change the contents of the entire 
8-element array. The following example 
shows the changing of contents of all 8 
words of the POS field with values’ taken 
from successive locations beginning with 
the user-specified source location: 


SSTORE (R1)+,PO0S,R3 


e To access a_e single element in the 
8-element array, you specify the 
3-character field name immediately 


followed by a numeric element number from 
0 to 7. In the following example, the 
user changes the contents of the first 
element of the POS field: 

SSTORE R2,P0S0,R1 


reg is a general register, RO through R5, loaded with 
the address of the user control block containing 
the desired data field. 
The following are examples of the SSTORE macro: 
SSTORE #0 ,ALQ,R3 
SSTORE #INPUT,FAB,R1 
In the first example, general register R3 contains the address of a 
File Access’ Block. The user clears the 2-word allocation quantity 
field (ALQ) in the block to zero. In the second example, general 
register Rl contains the address of a Record Access Block. The user 


stores the address of a File Access Block in the FAB field of the 
Record Access Block. 


4.6 S$TESTBITS - TESTING BITS WITHIN A FIELD 
The STESTBITS macro compares one or more bits within a I1-byte or 
l-word control block data field with a user-specified value and sets 
PDP-11 condition codes. 
The format of the $TESTBITS macro is as follows: 

label:STESTBITS source,fnm,reg 


where 


label is an optional user-specified symbol referring to 
the STESTBITS macro. 
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source is an expression or location indicating which bits 
of the specified data field are to be tested. 


fnm is the 3-character name of a l-byte or l-word bit 
string data field containing the bits to be 
tested. The assembler will generate an error 
message if the specified field name represents a 
multi-word field. 


reg is a general register, RO through R5, loaded with 
the address of the user control block containing 
the desired data field. 


In the following example of the $TESTBITS macro, the address of a File 
Access Block is in general register R3. The user tests the file 
access (FAC) field of the block to determine if the current program 
can issue SUPDATE or $PUT operations: 


STESTBITS #FBSUPD!FBSPUT,FAC,R3 


If neither bit is set in the FAC field, condition code Z will be set, 
if either or both bits are set in SHR, code Z will be off. 


CHAPTER 5 


THE FILE ACCESS BLOCK 


This chapter describes the File Access Block (FAB), the fields in a 
FAB, and the assembly-time macros that allocate FABs and initialize 
fields in FABs. 


Certain conventions apply to the assembly-time macros presented in 
this chapter and in Chapter 6 (The Record Access Block), Chapter 7 
(Extended Attribute Blocks), and Chapter 8 (The Name _ Block). For 
example, two macros are always required to allocate space for a user 
control block. These macros take the general form: 


1. label:xyz$B 


26 XyZSE 


label is the user-specified symbol that names. this 
particular block. 


xXyZ is the three character name of the control block 
to be allocated (i.e., FAB, RAB, XAB, NAM). 


An xyz$B macro causes the allocation of space for the specified block 
and delimits the beginning of an optional sequence of assembly-time 
initialization macros for the fields of the block. The xyzSE macro 
performs three functions: 


l. Stores the values specified by intervening initialization 
macros in appropriate locations in the block. 


2. Sets assembly-time default values in fields not explicitly 
initialized. 
3. Terminates the definition of the block. 
Each field within a user control block has a three character name. 
These three character names are always part of the name of the 


associated assembly-time initialization macros. The following is’ the 
format of initialization macros: 


x$fnm arg 
where 
x is the first character of the name of the block 


containing the field to be initialized, e.g., F 
for File Access Block, R for Record Access Block. 
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fnm is the three character name of the field to be 
initialized. 


arg is the value to be loaded into the _ specified 
field. 


The following are examples of assembly-time initialization macros: 


FSFAC arg 
R$ROP arg 


The FSFAC macro initializes the file access field (FAC) of the File 
Access’ Block. The RSROP macro initializes the record options field 
(ROP) of the Record Access Block. 


Assembly-time initialization macros can appear only between the xyzSB 
and xyzSE macros that define and allocate the control block containing 
the field to be initialized. 


The following are examples of the placement of field initialization 
macros: 


INFILE:FABSB 
FSFAC arg 
FABSE 


INP: RABSB 
RSROP arg 
RABSE 


Depending on the nature of the field being initialized, three types of 
arguments may appear on initialization macros: 


1. Symbolic values. 
2. Labels. 


3. Numeric values. 


NOTES 


1. You cannot use global symbols or labels 
as arguments to the assembly-time 
initialization macros described in this 
chapter. All symbols and labels used as 
arguments must be defined locally. 


2. The default radix for numeric values in 


assembly-time initialization macros is 
decimal. 


When symbolic values are provided by RMS-1l, they take the following 
form: 

xzSnam 
where 

XZ are the first and last characters of the 


associated three-character block name, e.g. FB 
for File Access Block, RB for Record Access Block. 
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nam is a two- or three-character symbolic name 
representing the value to be loaded into the 
specified field. 


The following are examples of symbolic values used as arguments’ in 
initialization macros: 


INFILE:FABS$B 
FSFAC FBSPUT 
FABSE 


INP: RABSB 
RSROP RBSEOF 
RABSE 


In the above examples, the file access field (FAC) of the File Access 
Block named INFILE is initialized with the symbolic value FBS$PUT. 
This value indicates that the user requires write access to the _ file 
associated with the block. The record options field (ROP) of the 
Record Access Block INP is initialized with the value RBSEOF. This 
value indicates that the file is to be positioned to end of file. 


When several symbolic values are used to initialize a field, each 
value must be separated by an exclamation point (!), as shown below: 


INFILE: FABSB 
FSFAC FBSGET!FBSPUT!FBSDEL 
FABSE 


The preceding example initializes the file access field (FAC) of the 
File Access Block INFILE with values indicating that the user requires 
read, write, and delete access to the contents of the associated file. 


Certain fields in user control blocks can contain the address of 
another block or program work area. The argument used in 
initialization macros for these fields is the label specified by the 
user for the second block or program work area. 


INFILE: FAB$B 
FABSE 


INP: RABSB 
RSFAB INFILE 
RABSE 


The preceding example shows the File Access Block address field (FAB) 
of the Record Access’ Block INP initialized with the address of the 
File Access Block named INFILE. 


Lastly, certain fields within structures may be initialized at 
assembly-time by macros that allow numeric values or user defined 
symbols as arguments: 


1. INFILE:FABSB 
FSMRS 132 
FABSE 


2. MAXSIZ=132. 


INFILE:FABSB 
FSMRS MAXSIZ 
FABSE 
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In the preceding examples, the maximum record size field (MRS) of a 
File Access Block named OTFILE is initialized with a value of 132, 
representing the size, in bytes, of the largest record that will be 
written in the file. 


5.1 ALLOCATING A FILE ACCESS BLOCK 


The FABSB macro allocates space for a File Access Block and delimits 
the beginning of an optional sequence of assembly-time initialization 
macros for the fields of the block. 


The format of the FABSB macro is as follows: 
label:FABSB 
where 


label is a user-specified symbol that names this 
particular File Access’ Block. You must assure 
that the address assigned to this label is 
word-aligned. Therefore, a .EVEN directive should 
immediately precede the FABSB macro. 


The FABSE macro delimits the end of an optional sequence of 
assembly-time initialization macros and stores any specified initial 
values in the appropriate fields of the block. At assembly-time, all 
fields not explicitly initialized are set to their default values. 
The FABSE macro must alwaysS appear subsequent to an associated FABSB 
Macro, even when no intervening initialization macros are coded. This 
macro takes the form: 


FABSE 


The following example shows the allocation of a File Access’ Block 
named MASTER: 


- EVEN 
MASTER: FABSB ;ALLOCATE MASTER FAB 
FABSE 7;END OF MASTER FAB 


The following example shows the allocation of the same block with the 
assembly-time initialization of two fields -- the file access (FAC) 
and logical channel number (LCH) fields. 


. EVEN 

MASTER: FABSB ;ALLOCATE MASTER FAB 
FSFAC FBSPUT ;ACCESS FOR $PUT OPERATIONS 
FSLCH 2 ;ACCESS FILE ON CHANNEL 2 
FABSE 7;END OF MASTER FAB 


5.2 FIELDS IN THE FILE ACCESS BLOCK 


Table 5-1 summarizes the fields in the File Access Block: 
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Table 5-1 
File Access Block Fields 


Description 


words Allocation quantity. 

byte Block identifier. 

byte Bucket size. 

byte Block length. 

word Block size. 

word Private buffer pool address. 
word Private buffer pool size. 

word User context area. 

word Default file extension quantity. 


byte Device characteristics. 
(bit string) 


1 word Default name string address. 
l byte Default name string size. 


l byte | File access. 
(bit string) 


1 word File name string access. 
1 byte File name string size. 


1 word File processing options. 
(bit string) 


byte Fixed control area size. 


word Internal file identifier. 
byte Logical channel number. 
words Maximum record number. 
word Maximum record size. 

word Name block address. 

byte File organization. 


byte Record attributes. 
(bit string) 


1 byte Record format. 


(Continued on next page) 
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Table 5-1 (Cont.) 
File Access Block Fields 


Description 


l byte Retrieval window size. 


1 byte File sharing. 


(bit string) 


1 word Completion status code. 
1 word Status value. 


1 word Extended attribute block pointer. 


The subsections that follow describe the purpose of each of the fields 
listed in Table 5-l. RMS-11 provides macros that allow you to 
initialize most of these fields at assembly-time. These macros, when 
provided, are discussed at the conclusion of each field description. 


5.2.1 ALQ - Allocation Quantity 


The allocation quantity (ALQ) field is used with three file processing 
macros - SOPEN, S$CREATE, and $EXTEND: 


1. As output from the SOPEN macro call, RMS-11l sets the ALQ 
field to indicate the highest numbered virtual block 
currently allocated to the file. 


2. Before creating a new file by issuing a S$CREATE macro 
call, you can set the ALQ field of the FAB describing 
the file. The value you place in ALQ will be 
interpreted by RMS-1ll as the number of virtual blocks to 
be contained in the initial extent of the file. If you 
set ALQ equal to zero, RMS-11 will determine the minimum 
number of virtual blocks that must be allocated for 
initial extent of the file. For sequential files, no 
blocks will be allocated. For relative and indexed 
files, the minimum number of virtual blocks is based on 
‘the attributes of the file. 


3. Before extending a file by issuing a $EXTEND macro call, 
you must set ALQ equal to the number of virtual blocks 
to be added to the file. 


NOTE 


The function of the ALQ field 
during the SCREATE and SEXTEND 
macro calls is different from the 
preceding descriptions if 
allocation XABs are present during 
the operation. Refer to Section 
7.6 in Chapter 7 for a description 
of allocation XABs and their effect 
on ALQ during $CREATE and SEXTEND 
operations. 
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The FSALQ macro allows you to initialize the ALQ field at 
assembly-time. The format of this macro is as follows: 


FSALQ quantity 
where 


quantity is a numeric value in the range of 0 to 16,777,215 
representing a number of virtual blocks. 


The following example of the FSALQ macro shows an allocation quantity 
of 132 virtual blocks. 


MASTER: FABSB 


FSALQ 132 


FABSE 


5.2.2 BID - Block Identifier 


The block identifier (BID) field identifies the block as a FAB. This 
field, automatically set by the FABS$B macro, contains the value 
FBSBID. You must never alter this field. 


5.2.3 BKS - Bucket Size 


The bucket size (BKS) field is used only for sxelative and indexed 
files. When you open an existing relative or indexed file by issuing 
the SOPEN macro call, RMS-11 sets the BKS field to the defined size of 
buckets in the file. When, however, you wish to create a relative or 
indexed file, you can specify the size of buckets in the file by 
setting a value in this field before issuing the SCREATE macro call. 
For sequential files, RMS-11l ignores the BKS field during a S$CREATE 
macro call and zeroes the field during a $OPEN macro call. 


NOTE 


The function of the BKS field during the 
SCREATE and SOPEN macro calls is 
different from the preceding description 
if allocation XABs are present during 
the operation. Refer to Section 7.6 in 
Chapter 7 for a description of 
allocation XABs and their effect on  BKS 
during $CREATE and SOPEN operations. 


In specifying a bucket size, you must be aware of the relationship 
between bucket size and record size. Since RMS-1l does not allow 
records to cross bucket boundaries, you should ensure that the number 
of virtual blocks per bucket conforms to one of the following 
formulas: 
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l. Indexed files with fixed length records: 


Bnum=( (Rlen+7) *Rnum) +15/512 


where 
Bnum is the number of virtual blocks per bucket 
rounded up to the next higher integer. The 
result must be in the range of from 1 to 32. 
Rlen is the fixed record length. 
Rnum is the number of records that you want in 


each bucket. 
2. Indexed files with variable length records: 


Bnum=( (Rmax+9) *Rnum) +15/512 


where 
Bnum is the number of virtual blocks per bucket 
rounded up to the next higher integer. The 
result must be in the range of from 1 to 32. 
Rmax is the maximum size of any record in the 
file. 
Rnum is the number of records, of the maximum 


size, that you want in each bucket. 


3. Relative files with fixed length records: 


Bnum = ((Rlen+1) *Rnum) /512 
where 
Bnum is the number of virtual blocks per bucket 
rounded up to the next higher integer. The 
result must be in the range of from 1 to 32. 
Rlen is the fixed record length. 
Rnum is the number of records that you want in 


each bucket. 
4. Relative files with variable length records: 


Bnum = ((Rmax+3) *Rnum) /512 


where 
Bnum is the number of virtual blocks per bucket 
rounded up to the next higher integer. The 
result must be in the range of from 1 to 32. 
Rmax is the maximum size of any record in the 
file. 
Rnum is the number of records that you want in 


each bucket. Variable length records ina 
relative file bucket always occupy Rmax+t3 
bytes. 
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5. Relative files with VFC format records: 


Bnum = ((Rmax+Fsiz+3) *Rnum) /512 


where 

Bnum is the number of virtual blocks per bucket 
rounded up to the next higher integer. 

Rmax is the maximum size of the data portion of 
any VFC record in the file. 

Fsiz is the size of the fixed control area portion 
of the VFC records. 

Rnum is the number of records that you want in 


each bucket. VFC records in a relative file 
bucket always occupy Rmax+Fsiz+3 bytes. 


The FSBKS macro allows you to initialize the BKS field at 
assembly-time. The format of this macro is as follows: 


FSBKS bucket-size 


where 
bucket-size is a numeric value, in the range of 0 to 32, 
representing the number of virtual blocks 
contained in each bucket of the file. The 


assembly-time default is 0. RMS-1ll interprets a 
value of 0 as identical to a value of l. 


The following is an example of the FSBKS macro showing the 
specification of four virtual blocks per bucket: 


MASTER: FABSB 


FSBKS 4 


5.2.4 BLN - Block Length 


The block length (BLN) field specifies the length of the FAB. This 
field, automatically set by the FABS$B macro, contains the value 
FBSBLN. You must never alter this field. 


5.2.5 BLS - Block Size 


The block size (BLS) field is used for files on magnetic tape. When 
you open an existing file on magnetic tape by issuing a SOPEN macro 
call, RMS-1ll sets the BLS field to the size of the physical blocks’ in 
the file. When, however, you are creating a file on magnetic tape, 
you can specify the physical block size by setting a value in this 
field before issuing the $CREATE macro call. 


THE FILE ACCESS BLOCK 


The FSBLS macro allows you to initialize the BLS field at 
assembly-time. Its format is: 


FSBLS block-size 
where 


block-size is a numeric value representing the size (in 
bytes) of the physical blocks on a tape. This 
value must be either 0 or in the range of 18 to 
8192 bytes. At runtime, a value of 0O is 
interpreted as the operating system default of 512 
bytes. The assembly-time default is 0. 


An example of the FSBLS macro follows: 


MASTER: FABSB 


FSBLS 4096 


FABSE 


In this example, the user specifies that each physical block in a 
Magnetic tape file will be 4096 blocks. 


NOTE. 


To allow data interchange with other DEC 
systems, you should specify a block size 
less than or equal to 512 bytes. To 
allow data interchange with non-DEC 
systems, you should specify a block size 
that is less than or equal to 2048 
bytes. 


5.2.6 BPA - Buffer Pool Address 


The buffer pool address (BPA) field can contain the address of a 
private I/O buffer pool for all record access streams for the file 
represented by the FAB. If you wish to use a private I/O buffer pool, 
you must set the address of the pool in this field before issuing a 
SCREATE or SOPEN macro call for the file. If you do not want to use a 
private I/O buffer pool for the file, you must assure that this field 
is zero before you issue the S$CREATE or S$OPEN macro. If this field is 
zero at the time a S$CREATE or SOPEN macro call is issued, RMS-11l 
allocates I/O buffers for the file from the centralized space pool 
(refer to Section 3.3.7 in Chapter 3). 


The FSBPA macro allows you to initialize the BPA field at 
assembly-time. The format of this macro is as follows: 


FSBPA address 
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where 


address is the symbolic address of the starting location 
of a private I/O buffer pool. This address must 
be on a double-word boundary. The assembly-time 
default for the BPA field iS zero (i.e., no 
private I/O buffer pool). 


In the following example, the user sets, at assembly~-time, the address 
of a private I/O buffer pool in the File Access Block called MASTER. 


. EVEN 
INBUF: .BLKB 4096. 


MASTER: FABSB 


FSBPA INBUF 


FABSE 


5.2.7 BPS ~ Buffer Pool Size 

You use the buffer pool size (BPS) field to specify the size of a 
private I/O buffer pool. You specify this size only if you placed a 
valid address in the BPA field of the same FAB before issuing a S$OPEN 
or SCREATE macro call. 


The FSBPS macro allows you to initialize the BPS field at 
assembly-time. Its format is: 


FSBPS poolsz 
where 
poolsz is a numeric value representing the total size (in 
bytes) of the private I/O buffer pool. The 


specified value must be a multiple of 4. 


To calculate the size of the private pool, you use the _ following 
formula: 


poolsz = stmsizel[+stmsize2...stmsizen] 


where 
stmsizel, are the I/O buffer space requirements (in bytes) 
stmsize2, for each simultaneously active record access 
etc. stream associated with the file. The requirements 


of each such stream are determined as follows: 
FOR DISK FILES 


stmsi1ze=BKS* (512*MBC) *MBF 
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where 
BKS is the number of virtual blocks in the largest 
size bucket of the file associated with the 
Stream. For sequential files, BKS equals 1 in 
this formula. 
MBC is the value contained in the multi-block 
count (MBC) field of the Record Access Block 
associated with the stream. This value is used 
only with sequential files. For non-sequential 
files, MBC equals 1 in this formula. 
MBF is the value contained in the multi-buffer 
count (MBF) field of the Record Access Block 
associated with the stream. 
FOR MAGNETIC TAPE FILES 
stmsize=BLS *MBF 
where 


BLS is the size (in bytes) of each physical block 
of the file associated with the stream. The 
default block size for magnetic tape files is 512 
bytes. 


MBF is the value contained in the multi-buffer 
count (MBF) field of the Record Access Block 
associated with the stream. 


In the following example, the user defines the address and size of a 
private I/O buffer pool: 


- EVEN 
INBUF: .~BLKB 4096. 


MASTER: FABSB 


FSBPA INBUF 
FSBPS 4096 


FABSE 


5.2.8 CTX - User Context Area 


The user context area (CTX) iS never used in any way by RMS-ll. It is 
intended exclusively for the user. Therefore, you can set any value 
you choose in this l-word field. You might, for example, use this 
field as a means of communicating with a common completion routine in 
your program. 


The FSCTX macro allows you to initialize the CTX field at 
assembly-time. The format of this macro is as follows: 


FSCTX argument 
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where 
argument represents any user-selected value. 


The following are two examples of the FS$CTX macro, showing a numeric 
value placed in the user context area in the first case, and a 
symbolic value in the second case. 


1. MASTER: FABSB 


FSCTX 3 


FABSE 


2. MASTER: FABSB 


FSCTX INPUT 


FABSE 


5.2.9 DEQ - Default File Extension Quantity 


The default file extension quantity (DEQ) field contains the number of 
virtual blocks to be used when RMS-11 must automatically extend the 
file. This automatic extension occurs whenever your program attempts 
a $PUT or S$UPDATE operation that cannot be accommodated within the 
Space currently allocated to the file. 


When you create a new file, you can specify a default extension 
quantity by setting the desired value in the DEQ field before issuing 
the SCREATE macro call. RMS-l1l1 saves the specified value as a 
permanent attribute of the file. A value of zero indicates that the 
default extension quantity for the file is the volume default. 


When you are processing an existing file, you can temporarily override 
the default extension quantity specified when the file was created. 
To do this, you set the desired value in the DEQ field before issuing 
the SOPEN macro call. When RMS-11 finds a non-zero value in this 
field during SOPEN processing, it uses the specified value for any 
automatic extension operations needed while the file is open. Once 
you close the file, the default extension quantity reverts to _ that 
specified at create time. 


The FSDEQ allows you to initialize the DEQ field at assembly-time. 
Its format is: 


FSDEQ quantity 
where 


quantity is a numeric value representing a number of 
virtual blocks. This number must be in the range 
of from 0 to 65,535. For relative and indexed 
files, the quantity you specify should be a 
multiple of bucket’ size. The assembly-time 
default is 0. 
5-13 
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The following example of the FSDEQ macros shows the user specifying a 
default extension of 80 virtual blocks. 


MASTER: FABSB 


FSDEQ 80 


FABSE 


5.2.10 DEV - Device Characteristics 


When you open a file by issuing a SOPEN or $CREATE macro call, RMS-11 
sets the device characteristics (DEV) field. This field allows RMS-1ll 
to communicate to your program the generic characteristics of the 
device on which the file resides. After the file is open, you can use 
appropriate runtime field accessing macros (refer to Chapter 4) to 
test for the following characteristics: 


FBSCCL Carriage control device, e.g., printers and 
terminals. 

FBSMDI Multiple directory structured device, e.g., disk 
volumes. 

FBSREC Record oriented device, e.g., terminal, line 


printer, etc. All record oriented devices are 
considered sequential in nature. 


FBSSDI Single directory device, i.e., a master file 
directory is used but no user file directories are 
present. 

FBSSQD Sequential and block oriented device (magnetic 
tape). 

FBSTRM Terminal with both keyboard and printer. 


5.2.11 DNA - Default Name String Address 
The default name string address (DNA) field allows you to _ provide 
program defaults for any missing components of the file name string 
addressed by the FNA field. You can specify defaults for one or more 
of the following file specification components: 

l. Device 

2. Directory 

3. Filename 


4. File type 


5. File version number 
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You can use the FSDNA macro to initialize the DNA _ field at 
assembly-time. The format of this macro is: 


FSDNA address 
where 


address is the symbolic address of an ASCII string 
representing one or more components of a file 
specification. The components (e.g., device, file 
type) must be specified in the order in which they 
would occur in a complete file specification 
string. If this field is zero, RMS-1l assumes 
that there is no default name string. 


As an example of the use of a default name string and the FS$DNA macro, 
assume that a user's program contains the following directive: 


DFNAM: .ASCII /SY:.DAT/ 


The following use of the FSDNA macro would associate the default name 
string with a particular File Access Block: 


MASTER: FABSB 


FSDNA DFNAM 


FABSE 


During a SOPEN or S$CREATE macro call, RMS-1l uses the ASCII string 
whose address is DFNAM to provide the device (SY:) and file type (DAT) 
components of the file specification of the file to be accessed -- if 
these components are missing from the string whose address is stored 
in the FNA field. 


5.2.12 DNS - Default Name String Size 

The default name string size (DNS) field is used to specify the size 
of the default name string whose address is contained in the DNA field 
of the same File Access Block. 


The FSDNS macro allows you to initialize the DNS field at 
assembly-time: 


FSDNS size 
where 
size is a numeric value representing the size of the 
default name string expressed in bytes. The 
specified value must be in the range of zero to 
255. If this field is zero, RMS-1l assumes that 
there is no default name string. 
Assume that a user's program contains the following directive: 


DFNAM: .ASCII /SY:.DAT/ 
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The following example shows the use of the FSDNS macro and its 
relationship to the FSDNA macro: 


MASTER: FABSB 


FSDNA DFNAM 
FSDNS 7 


FABSE 


5.2.13 FAC - File Access 


You must ensure that the file access (FAC) field contains indications 
of operations you intend to perform on the file. After you open a 
file, RMS-ll rejects any of the seven operations listed below if that 
operation was not specified in the FAC Field during execution of the 
SOPEN or SCREATE macro call for the file. 


SDELETE 

SGET 

$PUT 

STRUNCATE 

SUPDATE 

SREAD (block I/O) 
SWRITE (block I/O) 


If, for example, a $DELETE record operation macro appears in your 
program for the file associated with this File Access Block, the 
symbolic value FBSDEL must be present in the file access field before 
you open the file. 


The FSFAC macro allows you to initialize the FAC field at 
assembly-time. The format of this macro is as follows: 


FSFAC operation[!operation...] 
where 
operation is a symbolic value representing a type of file or 
record operation that may be performed on the 


file. One or more values may be listed in any 
order. Allowable values are: 


FBSDEL SDELETE operations. 


FBSGET SGET and/or SFIND operations 
(assembly-time default). 


FBSPUT SPUT operations. You must specify this 
value if you are creating a file. 


FBSREA SREAD block I/O operations (refer to 
Appendix B for a description of block 
I/O). 
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FBSTRN STRUNCATE operations. You should not 
specify this value unless the associated 
file is sequential. 


FBSUPD SUPDATE operations. 


FBSWRT SWRITE block I/0 operations (refer to 
Appendix B for a description of block 
I/O). 


The following are two examples of the FS$FAC macro, indicating $GET 
operations for the associated file in the first case, and $DELETE, 
SGET, and $PUT operations in the second case. 


1. MASTER: FABSB 


FSFAC FBSGET 


FABSE 


2. MASTER: FABSB 


FSFAC FBSDEL!FBSGET!FBSPUT 


e 


FABSE 


5.2.14 FNA - File Name String Address 


In combination with the file name string size field (FNS), the FNA 
field describes an ASCII string that represents the file specificaiton 
of the file associated with the File Access’ Block. If this string 
does not contain all the components of a full file specification, 
RMS-11 will use the defaults supplied in the default name _ string 
described by the DNA and DNS fields. If no default name string is 
present or if the file specification is still incomplete, RMS-1ll will 
apply system defaults, if any, for the missing components. 


The FSFNA macro allows you to initialize the FNA field at 
assembly-time. Its format is: 


FSFNA address 
where 


address is the symbolic address of an ASCII string 
representing the file specification of the file 
associated with the File Access’ Block. If this 
field is zero, RMS11 assumes that there is no file 
name string. 
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The following is an example of the FSFNA macro: 


FLNAM: .ASCII /PAYROLL/ 


MASTER: FABSB 


FSFNA FLNAM 


5.2.15 FNS - File Name String Size 


The file name string size (FNS) field contains the size of tthe ASCII 
String file specification whose address is in the FNA field of the 
block. 


The FSFNS macro allows you to initialize the FNS field at 
assembly-time. The format of this macro is: 


FSFNS size 
where 


size is a numeric value representing the size (in 
bytes) of the file name string. The specified 
value must be in the range of zero to 255. If 
this field is zero, RMS-1l1 assumes that there is 
no file name string. 


The following example shows the use of the FSFNS macro and its 
relationship to the FSFNA macro: 


FLNAM: .ASCII /PAYROLL/ 


MASTER: FABSB 


FSFNA FLNAM 
FSFNS 7 


FABSE 


5.2.16 FOP - File Processing Options 


The file processing options (FOP) field contains indicators 
representing your requests for optional file handling operations. 
This field can contain one or more of the following values: 


The 


where 


FBSCTG 


FBSDLK 


FBSNEF 


£23 POS 


FBSRWC 


FBSRWO 


FBSSUP 


FBSTMD 


FBSTMP 


FSFOP macro 
assembly-time. 


FSFOP 


option 
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indicates that, during a SEXTEND or SCREATE 
operation, RMS-1ll is to allocate contiguously the 
amount of space specified in the allocation 
quantity field (ALQ). For an existing file, 
RMS-1l returns this value in the FOP field 
following a SOPEN if the corresponding file is 
contiguous. 


indicates that the file is not to be locked from 
further access if it is not closed in the normal 
manner. 


inhibits positioning to end of file when an ANSI 
tape file is opened and the file access field 
(FAC) contains the symbolic value FBS$PUT. 


indicates that the magnetic tape volume set should 
be positioned to immmediately after the most 
recently closed file when the file represented by 
this File Access Block is created. The FBS$RWO 
value takes precedence over FBSPOS. The default 
operation is to position to the end of the volume 
set. 


specifies that the magnetic tape volume set is to 
be rewound when the file is closed. 


indicates that the magnetic tape volume set is to 
be rewound before the file associated with this 
File Access Block is opened or created. 


causes any corresponding existing file to be 
Superseded during a S$CREATE macro call if an 
explicit version number iS present in the full 
file specification of the file associated with 
this File Access Block. 


indicates that the file associated with tthe File 
Access’ Block is to be created as a temporary file 
and deleted when the file is closed. This value 
takes , precedence over the value FBSTMP, if both 
are present. 


indicates that a temporary file is to be created 
and retained after closing. The file name will 
not be entered in the directory. 


allows you to initialize the FOP field at 
Its format is: 


option[!option...] 


is a symbolic value representing a _ processing 
option to be applied to the file represented by 
the FAB. One or more of the options listed above 
can be specified. 
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In the following example of the FSFOP macro, the user requests’ that 
the magnetic tape volume is to be rewound when the file is closed. 


MASTER: FABSB 


FSFOP FBSRWC 


5.2.17 FSZ - Fixed Control Area Size 


The fixed control area size (FSZ) field is used only when the records 
of the file represented by the FAB are in VFC format. When you create 
such a file, you can set the desired value in the FSZ field before 
issuing the $CREATE macro call. When you open an existing file that 
contains VFC format records, RMS-1l will set this field equal to value 
specified when the file was created. 


You can initialize this field at assembly-time by using the FSFSZ 
macro. Its format is as follows: 


FSFSZ size 
where 


size is a numeric value, expressed in bytes, 
representing the size of the fixed control area of 
each record of the file. The specified value must 
be in the range of from 1 to 255. The default 
size is 2 bytes. If this field is zero, RMS-11 
assumes that the default size is desired. 


An example of the FSFSZ macro follows: 


. ~ MASTER: FABSB 


FSFSZ 8 


FABSE 


In this example, the user specifies that each record of the file (with 
VFC format records) contains an 8-byte fixed control area. 


5.2.18 IFI - Internal File Identifier 


The internal file identifier (IFI) field is used by RMS-1ll_ to 
associate the File Access Block with a corresponding internal control 
structure in the space pool. RMS-11 sets this field during a SOPEN or 
SCREATE operation. It is cleared to zero during a $CLOSE macro call. 
Your program must never alter this field. 
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5.2.19 LCH - Logical Channel Number 


The LCH field is used to indicate a logical channel number. Every 
File Access Block representing an open file must contain a unique 
logical channel number. All I/O operations performed on the _ file 
represented by a FAB will use this number. 


You can initialize the LCH field at assembly-time by using the FS$LCH 
macro. The format of this macro is as follows: 


FSLCH channel 
where 
channel is a numeric value from 1 to 255. 


In the following example, the user assigns a logical channel number of 
4 to the associated File Access Block: 


MASTER: FABSB 


FSLCH 4 


5.2.20 MRN - Maximum Record Number 


The maximum record number (MRN) field is meaningful only for relative 
files. When creating a relative file, you can use this field to 
specify the highest numbered record that can ever be written into the 
file. Thereafter, if any program attempts to write a record whose 
relative number exceeds the specified limit, RMS-11 will return an 
illegal maximum record number error (ERSMRN). Conversely, if you do 
not want to limit the number of records that can be written into a 
relative file, you set the MRN field to zero before issuing the 
SCREATE macro for the file. If the MRN field contained a value of 
zero at the time the file was created, RMS-11 will not perform limit 
checks when records are written. 


When you open an exiSting relative file by issuing a $OPEN macro call, 
RMS-1l1 returns to your program the MRN value specified when the file 
was created. If no MRN was’ specified, RMS-l1l returns the default 
value. 


You can initialize the MRN field at assembly-time by using the FSMRN 
macro: 


FSMRN max-rec-—num 


where 
max-rec—-num is a numeric value representing the highest 
numbered record that can be written into the file 
associated with the File Access’ Block. The 


assembly-time default is zero. RMS-1l converts a 
value of zero to the highest positive integer for 
the length of the field. It is this latter value 
that will be returned during a SOPEN operation if 
MRN was defaulted during a S$CREATE operation. 
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The following are two examples of the FSMRN_ macro. In the first 
example, the user indicates that the highest numbered record that can 
be written into the file is record 10,000. In the second example, the 
user explicitly specifies that no limit checks are to be performed. 


1. MASTER: FABSB 


FSMRN 10000 


FABSE 


2. MASTER: FABSB 


FSMRN 0 


5.2.21 MRS - Maximum Record Size 


When you create a file you should set the MRS field before issuing the 
SCREATE macro. The value you set in this field is based on the format 
of records in the file you are creating. 


Fixed format records - the specified value represents the actual 
size of each record in the file. When creating a new file with 
fixed format records, you must place a non-zero value in the MRS 
field. 


Variable and stream format records - the specified value 
represents the size of the largest record that can be written 
into the file. A value of zero means no limit on record size. 
The assembly-time default value is zero. However, if the 
organization of a file is relative, you must create the file with 
a non-zero maximum record size, which establishes the size of the 
record cells in the file. 


VFC format records - the specified value must not include the 
size of the fixed control area. Rather, the specified value 
represents only the remaining data portion of VFC_ records. 
Non-zero and zero values are interpreted by RMS-11 in the same 
manner as. in variable format records. 


When you open an existing file by issuing a SOPEN macro call, RMS-11 
returns, in the MRS field, the maximum record size specified when the 
file was created. 


The FSMRS macro allows you to initialize the MRS field at 
assembly-time. This macro takes the form: 


FSMRS size 
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where 


size is a numeric value expressed in bytes, 
representing record size. This value must be in 
the range of 0 to 16,383. 


In the following example, the user specifies a maximum record size of 
1024 bytes: 


MASTER: FABSB 


FSMRS 1024 


5.2.22 NAM - Name Block Address 


The Name Block address (NAM) field is always an optional field. You 
will place an address in this field only when you have allocated a NAM 
block in your program and want the facilities provided by such a block 
when you open a file (refer to Chapter 8 for a description of the 
purpose of a NAM block). 


You can initialize the NAM field at assembly-time with the FSNAM 
Macro. This macro takes the form: 


FSNAM address 
where 


address is the symbolic address of an optional name _ block 
associated with this File Access Block. A value 
of zero indicates no NAM block. The assembly-time 
default is zero. 


An example of the FSNAM macro follows: 


NMBLK: NAMSB 


NAMSE 


MASTER: FABSB 


FSNAM NMBLK 
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5.2.23 ORG - File Organization 


The organization (ORG) field identifies the organization of the file 
represented by the File Access Block. When you open an existing file, 
RMS-11 will set this field. When you create a new file, your program 
must set this field before issuing the S$CREATE macro call. 


The FSORG macro allows you to initialize the ORG field at 
assembly-time. Its format is: 


FSORG organization 
where 


organization is a symbolic value representing the organization 
of the file. One of the following values must be 
specified: 


FBSIDX - indexed 
FBSREL - relative 
FBSSEQ - sequential (assembly-time default) 


The following is an example of the FSORG macro: 


MASTER: FABSB 


FSORG FBSIDX 


FABSE 


In this example, the user specifies that the new file associated with 
the File Access Block is to have an indexed organization. 


5.2.24 RAT - Record Attributes 


The record attributes (RAT) field specifies characteristics of the 
records in the file. When you open an existing file, RMS-1l sets this 
field with the characteristics specified at create time. When you 
create a new file, your program sets desired values in this field 
before issuing the S$CREATE macro call. 


The FSRAT macro allows you to initialize the RAT field at 
assembly-time. It has the following format: 


FSRAT attribute[!attribute] 
where 
attribute is a symbolic value used to define an attribute of 
the records of the file. One or more values may 
be listed in any order. Allowable values are: 
FBSBLK indicates that records will not cross 


block boundaries. This value can be 
specified for sequential files only. 
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FBSCR indicates that each record, when written 
to a line printer or terminal, is to be 
preceded by a line feed character’ and 
followed by a carriage return character. 


FBSFITN specifies that the first byte of each 
record contains a FORTRAN carriage 
control character. 


In the following example, the user specifies that records do not cross 
block boundaries and each record is to be preceded by line feed and 
followed by carriage return when written to a carriage control device: 


MASTER: FABSB 


FSRAT FBSBLK!FBSCR 


5.2.25 RFM —- Record Format 


The record format (RFM) field indicates the format of the records in 
the file represented by the File Access Block. When you create a 
file, your program should ensure that the desired value is present in 
the RFM field before issuing the SCREATE macro. When you open an 
existing file, RMS-1ll sets this field with the value specified when 
the file was created. 


You can initialize the RFM field at assembly-time with the FSRFM 
macro. This macro takes the form: 


FSRFM record-format 
where 


record-format is a symbolic value defining the format of all 
records contained within the file. One of the 
following values can be specified: 


FBSFIX indicates fixed format records. 


FBSSTM indicates ASCII stream record format. 
This value can be specified only for 
sequential files on disk devices. 


FBS UDF indicates no record format is defined 
for the file. When creating a new file 
or accessing an existing file with 
undefined records, your program must use 
block I/O (refer to Appendix 8B). When 
creating such a file, the ORG field must 
specify sequential file organization. 


FBSVAR specifies variable format records 
(assembly-time default). 
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FBSVFC indicates VFC format records. This 
value can be specified for sequential 
(on disk devices only) or relative 
files. 


The following is an example of the FSRFM macro: 


MASTER: FABSB 


FSRFM FBSFIX 


5.2.26 RIV -— Retrieval Window Size 


The retrieval window size (RTV) field identifies the number of 
retrieval pointers you want RMS-11l to maintain in memory for the file 
represented by the File Access Block. 


The FSRTV macro allows you to initialize the RTV field at 
assembly-time. This macro takes the form: 


FSRTV number 
where 


number is either a positive integer in the range of 0 to 
127 or a -l1. A value of 0 (assembly-time default) 
indicates that RMS-1l is to determine a minimum 
window size. A non-zero poSitive value represents 
the actual number of retrieval pointers to _ be 
Maintained in memory. A -1l indicates that the 
entire file is to be mapped through a window 
maintained in memory. 


In the following example, the user requests a retrieval window of 10 
retrieval pointers. 


MASTER: FABSB 


FSRTV 10 


FABSE 


5.2.27 SHR - File Sharing 


The file sharing (SHR) field allows you to indicate whether you are 
willing to let other programs write to the file while your program has 
the file open at runtime (for either reading or writing). Note that 
sequentially organized files can be shared for reading only. However, 
RMS-11 permits relative and indexed files to be shared for both 
reading and writing. 
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You can initialize the SHR field at assembly-time by using the FSSHR 
macro. Its format is: 


FSSHR value 
where 


value is a symbolic value or 0. A value OF 0 
(assembly-time default) indicates that you do not 
want to share the file at runtime with any program 
that will write to the file. If, in contrast, you 
are willing to share the file with one or _ more 
programs that will write to the file, you can set 
this field with the following symbolic value: 


FBSWRI - allow shared writers. 


In the following example, the user indicates willingness to share the 
file with programs that write to the file: 


MASTER: FABSB 


FSSHR FBSWRI 


5.2.28 STS - Completion Status Code 


Before returning control to your program, RMS-1ll always sets’ the 
completion status code (STS) field to indicate success or failure of 
the file operation. Appendix A contains a complete list of symbolic 
completion codes that your program can use to test the contents of 
this field. . 


5.2.29 STV ~ Status Value 


Based on the type of operation performed and the contents of the STS 
field, RMS-1l1 may use the status value (STV) field to communicate 
additional completion information to your program (refer to Appendix A 
for a complete listing of the instances in which RMS-1l uses the STV 
field). 


5.2.30 XAB - Extended Attribute Block Pointer 


When a particular operation requires the association of Extended 
Attribute Blocks with a File Access Block, you set the address of the 
first associated block (of a potential chained list of such blocks) in 
the XAB field of the FAB. For example, when you create an indexed 
file, you must always provide at least one XAB -- a key definition XAB 
for the primary key. 


The FSXAB macro allows you to initialize the XAB field at 
assembly-time: 


FS$XAB xab-address 
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where 


xab-address is the symbolic address of the 


operation involving this FAB. 
The following is an example of the FSXAB macro: 


KEYDEF: XABSB XBSKEY 


MASTER: FABSB 


FSXAB KEYDEF 


FABSE 


In this example, KEYDEF is the label (address) 


Attribute Block. 


first 
Attribute Block associated with this File Access 
Block. A value of zero (assembly-time 
indicates no xXABS are _ present for a particular 


of 


an 


Extended 


default) 


Extended 
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THE RECORD ACCESS BLOCK 


This chapter describes the Record Access Block (RAB), the fields in a 
RAB, and the assembly-time macros that allocate RABs and initialize 
fields in RABs. 


Record Access Blocks are the second type of control structure that you 
allocate at assembly-time and use at runtime to communicate with 
RMS-11. During program execution, you associate (by issuing $CONNECT 
macro call) a Record Access Block with a File Access Block. The 
association of a RAB and a FAB is known aS a record access’ stream. 
Once you have established a record access stream, you use the fields 
of the Record Access Block to define to RMS-11 the next logical record 
you want to access in the file. 


6.1 ALLOCATING A RECORD ACCESS BLOCK 


The RABS$B macro allocates space for a Record Access Block and delimits 
the beginning of an optional sequence of assembly-time initialization 
macros for the fields of the block. 


The format of the RABSB macro is as follows: 
label:RABSB [type] 
where 


label is a user-specified symbol that names this 
particular Record Access Block. You must ensure 
that the address assigned to this label is 
word-aligned. Therefore, a .EVEN directive should 
immediately precede the RABSB macro. 


type indicates whether or not the Record Access’ Block 
can support asynchronous I/O operations (refer to 
Section 9.3.4 of Chapter 9 for a description of 
asyncronous record operations). One of the 
following values can be specified: 


SYN indicates synchronous record operations 
only (default). 


ASYN indicates that the RAB can support both 
synchronous and asynchronous’”~ record 
operations. 


The RABSE macro delimits the end of an optional sequence of 
assembly-time initialization macros and stores any specified initial 
values in the appropriate fields of the block. At assembly-time, all 
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fields not. explicitly initialized are set to their default values. 
The RABSE macro must alwaysS appear subsequent to an associated RABSB 
macro, even when no intervening initialization macros are coded. This 
macro takes the form: 


RABSE 


The following example shows the allocation for synchronous’ operations 
of a Record Access Block named INPUT: 


- EVEN 
INPUT: RABSB ;ALLOCATE INPUT RAB 
RABSE 7;END OF INPUT RAB 


The following example shows the allocation of the same block with’ the 
assembly-time initialization of two fields--the File Access Block 
address and Record Access (RAC) fields of the block. 


- EVEN 
INPUT: RABSB ;ALLOCATE INPUT RAB 
RSFAB MASTER ;ADDRESS OF ASSOCIATED FAB 
RS$RAC RBSSEQ  ;SEQUENTIAL ACCESS 
RABSE ;END OF INPUT RAB 


6.2 FIELDS IN THE RECORD ACCESS BLOCK 


Table 6-1 summarizes the fields in the Record Access Block: 


Table 6-1 
Record Access Block Fields 


Description 


Block identifier. 

Bucket code. 

Block length. 

User context area. 

File Access Block address. 
Internal stream identifier. 
Key buffer address. 

Key of reference. 

Key size. 

Multi-block count. 
Multi-buffer count. 


Record access mode. 


(Continued on next page) 
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Table 6-1 (Cont.) 
Record Access Block Fields 


Description 


word Record address. 
words Record's file address. 
word Record header buffer. 


word Record processing options. 


string) 


word Record size. 

word Completion status code. 
word Status value. 

word User record area address. 


word User record area size. 


The subsections that follow describe the purpose of each of the fields 
listed in Table 6-l. RMS-11 provides macros that allow you to 
initialize most of these fields at assembly-time. These macros, when 
provided, are discussed with the description of the associated field. 


6.2.1 BID - Block Identifier 
The block identifier (BID) field identifies the block as a RAB. This 


field, automatically set by the RABSB macro, contains the value 
RBSBID. You must never alter this field. 


6.2.2 BKT - Bucket Code 
The bucket code (BKT) field is used in two instances: 


1. When the record access stream represented by the RAB is 
performing I/O on a relative file. 


2. When the record access stream represented by the RAB is 
performing block I/O. 


When the record access stream is performing I/O on a relative file, 
RMS-1l1 sets the BKT field to the relative record number of the record 
accessed by an operation (e.g., $GET, $PUT). This feature is valid 
only when your program iS using sequential access mode. 


When performing block I/O, your program uses the BKT field to specify 
the virtual block number of a block to be read or written (refer to 
Appendix B for a description of block I/O). 

THE RSBKT macro initializes the BKT field at assembly-time: 


RSBKT vbn 
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where 


vbn is a numeric value representing a virtual block 
number. 


In the following example, the user specifies that the tenth virtual 
block of the file will be accessed when the program performs its first 
block I/O operation at runtime. 


INPUT: RABSB 


RSBKT 10 


RABSE 


6.2.3 BLN - Block Length 
The block length (BLN) field specifies the length of the _ RAB. This 
field, automatically set by the RABSB macro, contains the value RBSBLN 


for a synchronous RAB and the value RB$BLL for an asynchronous’ RAB. 
You must never alter this field. 


6.2.4 CTX — User Context Area 

The user context area (CTX) is never used in any way by RMS-1l. It is 
intended exclusively for the user. Therefore, you can set any value 
you choose in this l-word field. You might, for example, use this 
field as a means of communicating with a common completion routine in 
your program. 


The RSCTX macro allows you to initialize the CTX field at 
assembly-time. The format of this macro is as follows: 


RS$CTX argument 
where 

argument represents any user-selected value. 
The following are two examples of the RSCTX macro, showing a numeric 
value placed in the user context area in the first case, and a 


symbolic value in the second case. 


1. INPUT: RABSB 


RSCTX 1 
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2. INPUT: RABSB 


RS$CTX MASTER 


RABSE 


6.2.5 FAB - File Access Block Address 

The FAB field must contain the address of a File Access’ Block 
associated with an open file at the time a S$CONNECT macro call (refer 
to Section 9.3.1) is issued for the current Record Access Block. 


The RSFAB macro allows you to initialize the FAB field at 
assembly-time. Its format is as follows: 


RSFAB fab-address 
where 

fab-address is the symbolic address of a File Access Block. 
The following is an example of a RS$FAB macro: 


MASTER: FABSB 


INPUT: RABSB 


RSFAB MASTER 


6.2.6 ISI - Internal Stream Identifier 


The internal stream identifier (ISI) field is used by RMS-11 to 
associate the Record Access Block with a corresponding internal 
control structure in the space pool. RMS-1l sets this field during a 
SCONNECT operation. Your program must never alter this field. 


6.2.7 KBF - Key Buffer Address 


The key buffer address (KBF) field contains the address of a_ location 
in your program. You will use this location during certain operations 
in random access mode to indexed and relative files. 
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Before issuing a $GET or S$FIND operation in random mode to an. indexed 
file, you place in KBF the address of a location containing a 
character string key value. The size of this character string must be 
specified in the KSZ field. During execution of the $GET or $FIND 
operation, RMS-1l uses the character string described by the KBF and 
KSZ fields to search an index (which you specify through the contents 
of the KRF field of the RAB) and locate the desired record in the 
file. The type of match (i.e., exact, generic, approximate, or 
approximate and generic) that RMS-11l attempts between the character 
string you specify and key values in records of the file is determined 
by the KSZ field and the ROP field. 


Before issuing a $GET, $FIND, or $PUT operation in random mode to a 
relative file, you must place in KBF the address of a location 
containing a relative record number (note that relative record numbers 
for a relative file begin with 1). The size of this location must be 
in the KSZ field and must always equal 4. 


The RSKBF macro allows you to initialize the KBF field at 
assembly-time. The format of this macro is: 


RSKBF address 
where 
address is the symbolic address of a location containing 
the key value or relative record number of a 
record. RMS-1ll does not require that this address 
be word-aligned. The size of this field is 
specified by the KSZ field. When a relative file 
is being accessed, the address in KBF points to 
the least significant bits of the desired relative 
record number. 
The following is an example of the RSKBF macro: 


INKEY: BLKB 32. 
INPUT: RABSB 


RS KBF INKEY 


6.2.8 KRF - Key of Reference 


The key of reference (KRF) field is meaningful only when an_ indexed 
file is being processed. It is used when your program: 


l. Issues $GET or $FIND operations in random access mode to 
indexed files. 


2. Issues $CONNECT or $REWIND operations for indexed files. 
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During random $GET or $FIND operations, the contents of the KRF_ field 
specify which key field is described by the KBF and KSZ fields, e.g., 
primary key, first alternate key, etc. Thus, KRF tells RMS-11 which 
index in the file to search seeking a match on the character string 
key value you described through the contents of the KBF and KSZ 
fields. 


During $CONNECT or S$REWIND operations, RMS-1l uses the contents of the 
KRF field to determine the current context of the record access stream 
(refer to Section 9.3.3 in Chapter 9 for a discussion of current 
context). In this case, KRF identifies an index of the file which, in 
turn, identifies the next record for the stream. 


The RSKRF macro can be used to initialize the KRF field at 
assembly-time. The following is the format of this macro: 


RSKRF key-number 
where 


key-number is a numeric value representing a key within the 
records of the file. A value of zero indicates 
the primary key. Values of 1 through 254 indicate 
the desired alternate keys. The assembly-time 
default value is zero (primary key). 


In the following example, the user specifies that the contents of the 
location called INKEY represent a first alternate key value. 


INKEY: BLKB 32. 
INPUT: RABSB 


RSKBF INKEY 


6.2.9 KSZ - Key Size 


The key size (KSZ) field contains the size of the location whose 
address is in the KBF field of the block. 


When you access an indexed file in random mode, you use the _ contents 
of the KSZ and ROP fields to specify the type of match that RMS-11 is 
to perform on the character string key value addressed by the KBF 
field. If the size in KSZ equals the length of the key field as 
defined when the file was created, RMS-1l attempts an exact match (if 
neither RBSKGE or RBS$KGT is present in ROP) or an approximate match 
(if RBSKGE or RBSKGT is present in ROP). If, however, the size in KSZ 
is less than the defined key length, RMS-1l attempts a generic match 
(RBSKGE or RBS$KGT not in ROP) or a generic~approximate match (either 
RBS$SKGE or RBSKGT present in ROP). 


When you access a relative file in random mode, you must ensure that 
KSZ contains the value 4. 
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The RSKSZ macro allows you to initialize this field at assembly-time. 
The format of this macro is as follows: 
RS$KSZ size 
where 
size is a numeric value representing the size (in 
bytes) of the record key. The specified value 
must be in the range of 1 to 255. 


The following is an example of the RSKSZ macro: 


INKEY: BLKB 32. 


INPUT: RABSB 


RSKSZ 32 
RSKRF 1 
RABSE 


In this example, the user specifies that the first alternate key value 
in location INKEY is 32 bytes in length. 


6.2.10 MBC - Multi-block Count 


Use of the multi-block count (MBC) field is optional. It applies only 
when the stream represented by the RAB is accessing a Sequentially 
organized file on disk. 


The contents of the MBC field, examined by RMS-11 during execution of 
the SCONNECT macro, represent the number of virtual blocks you want 
transferred as a Single entity during I/O operations between the file 
and each of the stream's buffers. Effectively, therefore, the MBC 
field defines the size of each buffer supporting the stream's access 
to the file while the MBF field (refer to Section 6.2.11) specifies 
the number of such buffers RMS-11 is to allocate for the stream. 


The primary use of the MBC field is for throughput optimization. It 
in no way effects the structure of the file being accessed. Rather, 
it minimizes the number of disk accesses required to support your 
program's record operation requests. In particular, if your program 
issues all read requests (S$GETs) or all write requests ($PUTs), you 
can increase execution speed by specifying at $CONNECT time an MBC 
value that is greater than 1. In combination with this value, you 
must ensure that the central space pool (refer to Section 3.3.7 in 
Chapter 3) or your private I/O buffer pool (refer to Section 5.2.7 in 
Chapter 5) contains sufficient space for the larger buffers. 


The RSMBC macro initializes the MBC field at assembly-time. Its 
format is: 


RSMBC_ blocks 
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where 


blocks is a numeric value from 0 to 255 representing the 
number of blocks to be transferred during I/O 
operations and, therefore, the number of virtual 
blocks contained in each I/O buffer supporting the 
stream. The assembly-time default is 0. Both 0 
and 1 indicate 1 block per buffer. 


In the following example, the user specifies that 8 virtual blocks are 
to be transferred during each I/0 operation between the stream's 
buffers and the file. 


INPUT: RABSB 


RSMBC 8 


6.2.11 MBF - Multi-buffer Count 


The contents of the multi-buffer count (MBF) field represent’ the 
number of I/O buffers you want RMS-11 to allocate when your program 
issues a SCONNECT operation for this Record Access’ Block. RMS-11 
allocates these buffers either from the centralized space pool or, if 
the BPA and BPS fields are non-zero in the FAB associated with this 
RAB, from the private I/O buffer pool associated with the file. 


The minimum number of buffers that RMS-11 requires for a record access 
stream is based on the organization of the file. Table 6-2 lists the 
minimum number of buffers for each file organization and the maximum 
number of buffers that you can specify. 


Table 6-2 
Minimum and Maximum Number of Buffers 


File Minimum Maximum 
Organization MBF MBF 


Sequential 2 
Relative No maximum 


Indexed No maximum 


The RSMBF macro allows you to initialize the MBF field at 
assembly-time. The format of this macro is: 


RSMBF buffers 


where 


buffers 
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is a numeric value representing the number of 
buffers to be allocated to the record access 
stream upon execution of a $CONNECT macro call. 
The specified value must be in the range of 0 to 
255% A value of 0 (assembly-time default) 
indicates the minumum number of buffers based on 
the file's organization. If the user specifies 
less than the minimum required by the organization 
of the file, RMS-1l ignores the user specification 
and allocates the minimum required. If the user, 
for a sequential file, specifies more than _ the 
maximum, RMS-11 allocates the maximum number (2). 
If the user specifies more buffers than are 
available, RMS-11l allocates as many as possible. 


In the following example, the user specifies the allocation of four 


buffe 


rss 


INPUT: RABSB 


4 


6.2.12 RAC - Record Access Mode 


The RAC field specifies the access mode to be used to retrieve or 


store 


The 
assem 


where 


a record. 


RSRAC macro 


bly-time. 


allows you to initialize the RAC field at 
Its format is: 


RSRAC access-mode 


access-mode 


is a symbolic value representing the type of 
access desired. One of the following may be 
specified: 


RBSKEY indicates random access. You can 
specify this value only with relative or 
indexed files. 


RBSRFA indicates access by record's file 
address (for files on disk devices 
only). When you specify this value, 
RMS-11 uses the record's file address 
(RFA) field of this RAB to access’ the 


record. 

RBSSEQ indicates sequential access. You can 
specify this value with any file 
Organization. 
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The following is an example of the RS$RAC macro in which the user 
indicates random access: 


INPUT: RABSB 


RSRAC RBSKEY 


RABSE 


6.2.13 RBF - Record Address 


The record address (RBF) field is used to pass the address of a record 
between RMS-1l and your program. As output from a successful $GET 
operation, RMS-1l always places the memory address of the retrieved 
record in RBF. Conversely, your program, prior to a $PUT or S$UPDATE 
operation, must place in RBF the memory address of the record to _ be 
written out to the file. In both instances, the RSZ field describes 
the size of the record. Refer to Section 9.3.5.2.1 in Chapter 9 for 
further details on the RBF and RSZ fields. 


You can initialize the RBF field at assembly-time with the RSRBF 
macro. The format of this macro is as follows: 


RSRBF address 
where 


address is the symbolic address of an area in your 
program. 


In the following example, the user initializes the RBF field with the 
address of a program location that, at runtime, will contain a record 
to be written to the file. 


RECBUF: .BLKB 150. 


INPUT: RABSB 


RSRBF RECBUF 


6.2.14 RFA - Record's File Address 


The record's file address (RFA) field is used to pass the RFAs of 
records between RMS-1l and your program. After successful $GET, $PUT, 
and $FIND operations, RMS-1ll returns to your program the RFA of the 
record successfully operated upon. Your program can then save the 
contents of this field for subsequent retrieval of the record using 
RFA access mode. Before retrieving a record uSing RFA access, your 
program must load the RFA of the desired record in the RFA field. 


6-11 
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6.2.15 RHB - Record Header Buffer 


RMS-11 uses the record header buffer (RHB) field only when the record 
format field (RFM) of the associated File Access Block indicates VFC 
format records. When RHB is non-zero, RMS-1ll interprets its contents 
as the address of a buffer for the fixed control area portion of VFC 
records. On S$GET operations, RMS-ll strips the fixed control area 
portion of VFC records and places it in the buffer whose address is in 
the RHB field. On $PUT and SUPDATE operations, RMS-1l prefixes’ the 
data portion of the record with the fixed control area portion 
described by the RHB field before the entire record is written to’ the 
file. For all such operations, the size of the fixed control area 
portion is a defined attribute of the file. During a S$OPEN macro 
call, RMS-1l returns this size in the FSZ field of the associated File 
Access Block. When your program processes the fixed control area 
portion of VFC records, you must ensure that the buffer described by 
the RHB field is at least as large as the value in FSZ. 


When you do not want to process the fixed control area portion of VFC 
records, you zero the RHB field. When RHB is zero, RMS-11 does the 
following: 


1. Skips the fixed control area portion of the record on _ S$GET 
operations. 4 


2. Writes out a zero-filled fixed control area on SPUT 
operations. 


3. Leaves the original fixed control area unaltered on $UPDATE 
operations. 


You can initialize the RHB field at assembly-time with the RSRHB 
macro: 


RSRHB header-address 
where 
header-address is the symbolic address of an area within your 


program. An address of zero in the RHB field 
indicates the nonexistence of the buffer. 


6.2.16 ROP -— Record Processing Options 


The record processing options (ROP) field allows you to _ request 
optional functions during the execution of a record operation. 


The RSROP macro allows you to initialize the ROP field at 
assembly-time. The format of this macro is as follows: 


RSROP option[!option...] 
where 
option is a symbolic value representing record processing 


options. One or more of the following options may 
be specified in any order. 
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RBSASY 


RBSEOF 


RBSFDL 


RBS$KGE 


RBS$KGT 


RBS$SLOA 


RBSLOC 


indicates asynchronous operation. When 
this value is set, RMS-11 can return 
control to your program before the 
specified record operation is completed 
(assuming that the RAB has been defined 
as asynchronous in the RABSB macro). 


indicates that RMS-1l is to position to 
end of file when the SCONNECT macro call 
is issued for the record access’ stream. 
This option applies only to sequential 
files on disk devices. 


indicates fast delete (indexed files 
only). When this value is present, 
SDELETE operations will mark records in 
the file as deleted but RMS-11 will not 
remove pointers to the record from. the 
indexes. 


indicates that RMS-1l is to search for 
the first record containing a value in 
the key specified by the KRF field that 
is greater than or equal to the value 
described by the KBF and kKSZ _ fields. 
This option applies only to indexed 
files and is one form of the approximate 
match facility (see also RBS$KGT). 


specifies the second form of the 
approximate match facility (see also 
RBSKGE). It indicates that RMS-1ll is to 
search for the first record containing a 
value in the key specified by the KRF 
field that is greater than the value 
described by the KBF and KSZ_§ fields. 
This option applies only to indexed 
files. 


indicates that RMS-ll is to follow 
bucket fill sizes for record insertions 
to indexed files. The fill sizes for a 
file are specified by the user at file 
creation time in the DFL and IFL fields 
of key . definition XABs. The 
assembly-time default is to ignore . 
bucket fill sizes (i.e., buckets will be 
completely filled). 


indicates locate mode. Locate mode _ on 
SGET operations is supported for all 
file organizations. Locate mode on $PUT 
operations is supported only for 
sequential files. Locate mode is not 
permitted if the file was opened for 
SUPDATE operations (i.e., the value 
FBSUPD was present in the FAC field of 
the FAB during the SOPEN or SCREATE 
operation). 
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RBSUIF indicates that if a $PUT operation to a 
relative file encounters an existing 
record in the target record cell, the 
existing record is to be updated. If 
RBSUIF is not set, RMS-1l returns an 
ERSREX (record already exists) error if 
a $PUT operation to ae relative file 
encounters an existing record. 


The following are two examples of the RS$ROP macro. In the first 
example, the user specifies positioning to end of file and locate mode 
operations. In the second example, the user specifies an approximate 
key search, i.e., RMS-1l is to search for a record containing a key 
value equal to or greater than the key described by the KBF, KSZ, and 
KRF fields. 


1. INPUT: RABSB 


RSROP RBSEOF ! RB$ LOC 


2. INPUT: RABSB 


RS$ROP RBS$KGE 


6.2.17 RSZ - Record Size 


The record size (RSZ) field contains the size (in bytes) of the record 
whose address is in the RBF field. Following a successful $GET 
operation, RMS-1l places the size of the retrieved record in the RSZ 
field. Conversely, your program, before issuing a $PUT or SUPDATE 
operation, must ensure that the RSZ field contains the size of the 
record to be written. 


The RSRSZ macro can be used to initialize the RSZ field at 
assembly-time. The format of this macro is: 


RS$RSZ record-size 
where 
record-size is a numeric value representing the size (in 
bytes) of the record whose address is in the RBF 


field. The value specified must range from 1 to 
16383. 
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The following is an example of the RS$RSZ macro: 


RECBUF: .BLKB 150. 


INPUT: RABSB 


RSRBF RECBUF 
RS$RSZ 150 


RABSE 


In this example, the user specifies a record size of 150 bytes. 


6.2.18 STS -—- Completion Status Code 


RMS-11 always sets the completion status code (STS) field to indicate 
success or failure of the record operation. Appendix A contains a 
complete list of symbolic completion codes that your program can _ use 
to test the contents of this field. 


6.2.19 STV — Status Value 


Based on the type of operation performed and the contents of the STS 
field, RMS-ll may use the status value (STV) field to communicate 
additional completion information to your program (refer to Appendix A 
for a complete list of the instances in which RMS-1ll uses the STV 
field). 


6.2.20 UBF - User Record Area Address 


The user record area address (UBF) field must contain a valid address 
regardless of the data transfer mode (i.e., move or locate mode) 
associated with the record access stream. Refer to Section 9.3.5.2.2 
in Chapter 9 for details on the function of the UBF field. 


The RSUBF macro allows you to initialize the UBF field at 
assembly-time. The format of this macro is: 


RSUBF address 
where 
address is the symbolic address of a work area within your 


program. You must specify the size of this work 
area in USZ. 
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The following is an example of the RSUBF macro. 


WAREA: .BLKW 1024. 
INPUT: RABSB 


RSUBF WAREA 


RABSE 


6.2.21 USZ — User Record Area Size 


The USZ field contains the size of the user record area whose address 
is in the UBF field. 


You can initialize the USZ field at assembly-time with the RS$US2 
macro: 


RS$USZ area-size 
where 
area-size is a numeric value representing the size (in 
bytes) of the user record area whose address is in 


the UBF field. The value specified must’ range 
from 1 to 16383. 


In the following example, the user specifies a user record area 2048 
bytes in size. 


WAREA: .BLKW 1024. 
INPUT: RABSB 


RSUBF WAREA 
RS$USZ 2048 


RABSE 


CHAPTER 7 


EXTENDED ATTRIBUTE BLOCKS 


This chapter describes Extended Attribute Blocks, the fields in 
Extended Attribute Blocks, and the assembly-time macros that allocate 
XABs and initialize fields in XABs. 
Extended Attribute Blocks’ contain file and record attribute 
information beyond that specified in the associated File Access Block. 
XABS are generally required only when a file is being created 
(particularly an indexed file) or when the S$DISPLAY macro call is used 
to retrieve file attributes. 
When more than one Extended Attribute Block is required, they are 
linked together. The XAB field of the File Access Block points to the 
first block in the linked list. 
There are five types of Extended Attribute Blocks: 

l. Date and time XABs 

2. Key definition XABs 

3. File protection specification XABs 

4. Allocation XABs 

5. Summary XAB 


After descriptions of XAB allocation and linking, Ae subsections that 
follow describe each type of XAB. 


7.1 ALLOCATING AN EXTENDED ATTRIBUTE BLOCK 


The XAB$B macro allocates space for an Extended Attribute Block and 
delimits the beginning of an optional sequence of assembly-time 
initialization macros for the fields of the block. 


The format of the XAB$B macro is as follows: 
label:XABSB type 
where 
label is a user-specified symbol that names this 
particular Extended Attribute Block. You must 
ensure that the address assigned to this label is 


word-aligned. Therefore, a .EVEN directive should 
immediately precede the XABSB macro. 


EXTENDED ATTRIBUTE BLOCKS 


type is a symbolic value representing the type of 
attribute information contained in the block. At 
assembly-time, the specified value is stored in 
the COD field of the block. At runtime, the value 
in the COD field determines how RMS-1l interprets 
the remainder of the Extended Attribute Block. 


One of the following values must be specified at 
assembly-time. 


XBSDAT indicates a date and time XAB. 

XBSKEY | iauiecses a key definition XAB. 

XB$ PRO indicates a file protection 
specification XAB. 

XBSALL indicates an allocation XAB. 

XBSSUM indicates a summary XAB 


The XABSE macro delimits the end of an optional sequence of 
assembly-time initialization macros and stores any specified initial 
values in the appropriate fields of the block. At assembly-time all 
fields not explicitly initialized are set to their default values. 
The XABSE macro must always appear subsequent to an associated XABSB 
macro, even when no intervening initialization macros are coded. This 
macro takes the form: 


XABSE 


The following example shows the allocation of a key definition 
Extended Attribute Block named KEYDEF: 


- EVEN 
KEYDEF: XABSB XBSKEY 
XABSE 


7.2 LINKING AND ORDERING EXTENDED ATTRIBUTE BLOCKS 


Regardless of the type of information contained (e.q., key definition, 
protection specification, etc.), every XAB has an NXT field. The NXT 
field links one XAB with another. When multiple XABs are needed for a 
particular operation (e.g., SCREATE, SDISPLAY), the address of the 
first XAB is placed in the XAB field of the File Access’ Block. The 
address of the second XAB is placed in the NXT field of the first XAB, 
and so forth. The NXT field of the last XAB in the linked chain is 
set to zero to indicate the end of the chain. 


Within a chain of XABs, there is no mandatory ordering of blocks based 
on XAB_ type (i.e., contents of the COD field). Assume, for example, 
that you want to obtain the attributes of a single-key indexed file. 
At assembly-time, you could allocate a date and time XAB, a key 
definition XAB, a file protection XAB, and a summary  XAB. Then, 
either at assembly-time or at runtime, -you could link these XABs in 
any order by appropriately setting the contents of the NXT field in 
each block. Finally, you would issue a $DISPLAY macro call and RMS-11 
would fill attribute information into each block -- the type of 
information going into each block being determined by the COD field of 
the block. 


7-2 


EXTENDED ATTRIBUTE BLOCKS 


While different types of XABsS can appear in any order in ae chain, 
multiple instances of the same type must appear in a particular order. 
This rule applies to key definition and allocation XABs, since’ these 
are the only ones that RMS-1l permits multiple instances of ina 
chain. Key definition XABs must be linked together in ascending order 
based on the contents of the key of reference (REF) field (refer to 
Section 7.4.10). Allocation XABs must be linked together in ascending 
order based on the contents of the area identification number (AID) 
field (refer to Section 7.6.1). In both instances, there cannot be 
any intervening XABs of another type in the sub-chain of XABs of the 
same type. Further, the operation for which these XABs_ are present 
determines. whether or not the ascending order must be dense. For 
SCREATE operations, key definition and allocation XABs, if present, 
must appear in densely ascending order by, respectively, key of 
reference (REF) and area identification number (AID). For SOPEN, 
SEXTEND, and SDISPLAY operations, key definition and allocation XABs, 
if present, must be in ascending order but need not be dense. 


You use the XSNXT macro to initialize the NXT field of an XAB at 
assembly-time. The format of the X$NXT macro is as follows: 


XSNXT xab-address 
where 


xab-address is the symbolic address of the next XAB within the 
current chain of XABs. A value of zero indicates 
the last (or only) XAB in a chain. 


7.3 DATE AND TIME EXTENDED ATTRIBUTE BLOCKS 


Date and time Extended Attribute Blocks contain fields specifying the 
date and time the associated file was created and the date and time 
the file was last updated. There are no initialization macros for the 
fields in this XAB since you can only examine, but not alter, the date 
and time attributes of a file. The allocation of this XAB at 
assembly-time causes the fields of the block to be initialized to 
zero. 


Table 7-1 describes the fields of a date and time XAB. 


Table 7-1 
Date and Time XAB Fields 


4 words The date and time the file was 
created, expressed as an 8 byte 
binary number. 


byte Code field. Contains the value 
XBSDAT. 


word Next XAB. 
words The date and time the file was last 


updated, expressed as an 8 byte 
binary number. 


Revision number. Contains the 
number of times the file was opened 
(via a SOPEN macro call) for write 
operations. 
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The 8-byte binary numbers (in which the lowest-addressed byte is the 
least significant) in the CDT and RDT fields represent the number of 
hundreds of nanoseconds elapsed since the beginning of November 17, 
1858. 


7.4 KEY DEFINITION EXTENDED ATTRIBUTE BLOCKS 


Each key definition Extended Attribute Block describes one key of an 
indexed file. When you create an indexed file, you must set the 
contents of the fields of this XAB before you issue the $CREATE macro 
call. You must, further, provide one key definition XAB for each key 
you want the file to have. Since every indexed file has at least one 
key (the primary key) you will always require at least one key 
definition XAB. 


When you open an existing indexed file or issue a $DISPLAY operation 
for such a file, you use key definition XABs only if you want RMS-1l1, 
as output from the macro call, to provide your program with one or 
more of the key definitions specified when the file was created. 

Table 7-2 summarizes the fields of a key definition XAB. 


Table 7-2 
Key Definition XAB Fields 


1 byte 


Code field. Contains the value 
XBSKEY. 


Area number for data buckets. 


byte 


Data bucket fill size. 


word 


byte 
string) 


Key options. 


byte Area number for index buckets. 


word Index bucket fill size. 


word Key name address. 


Area number for lowest level 


index. 


byte 


byte Null key value. 


word Next XAB. 


words Key position. 


byte Key of reference. 


words Root virtual block number. 


bytes Key size. 
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The following subsections describe the fields listed in Table 7-2 that 
are unique to the key definition XAB. 


7.4.1 DAN - Area Number for Data Buckets 


You set a value in the DAN field only if both of the following are 
true: 


1. You are creating a new indexed file. 


2. You are using allocation XABs (described in Section 7.6) to 
control the placement and structure of the file. 


If both of the above are true, then you use the DAN field to assign 
the buckets of the data level of the index defined by this XAB to one 
of the areas defined by an allocation XAB. 


When the key definition XAB describes the primary key, the data level 
of the index consists of those buckets containing the actual data 
records of the file. When, however, the XAB describes an alternate 
key, the data level of the index consists of buckets in which RMS-11 
Maintains pointer arrays describing the data records. 


The X$DAN macro allows you to initialize the DAN field at 
assembly-time. Its format is: 


X$DAN aid 


where 
aid is a numeric value from 0 to 254 representing an area 
identification number contained in the AID field of an 
allocation xXAB present in the same chain. The 


assembly-time default is 0 (i.e., area OQ). 


In the following example, the user assigns the data level of the key 
defined by the XAB called KEYDEF to area l. 


AREA1: XABSB XBSALL 


KEYDEF: XABSB XBSKEY 
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7.4.2 DFL - Data Bucket Fill Size 


At SCREATE time, you can use the DFL field to specify how many bytes 
you want used in each data level bucket of the associated index. By 
specifying less than the total bucket size, you indicate that the data 
buckets are not to be completely filled but are to contain some amount 
of free space. At runtime, RMS-11 adheres to the fill size specified 
at SCREATE time only if the RBS$LOA value is present in the record 
processing options (ROP) field of the RAB. 


When the key definition XAB describes the primary key, the DFL field 
describes space in buckets containing the actual user data records. 
When the XAB describes an alternate key, the DFL field describes space 
in buckets of the alternate index containing pointers to the user data 
records. 


You may want to use the facility provided by the DFL field (and the 
Similar facility provided by the IFL field, described in Section 
7.4.5) in the following situation: If you expect to perform numerous 
S$PUT and S$UPDATE operations on the file after it has been initially 
populated, you can minimize the resultant movement of records (known 
as bucket splitting) by specifying a less than maximum bucket fill 
Size at S$CREATE time. To utilize the free space thereby reserved in 
the buckets, programs that perform $PUT or SUPDATE operations on the 
file should not place, at $CONNECT time, the value RBSLOA in the ROP 
field of the RAB. 


The XS$DFL macro allows you to initialize the DFL field at 
assembly-time. The format of this macro is: 


XSDFL space 
where 


space is a numeric value representing the maximum number 
of bytes to be used in the data buckets. The 
assembly-time default value is 0, which is 
interpreted at runtime by RMS-11 as meaning the 
bucket size in bytes (i.e., no unused space). 


The following is an example of the XSDFL macro: 


KEYDEF: XABS$B XBSKEY 


XSDFL 256 


XABSE 


In this example, the user specifies that each bucket in the data level 
is to be filled to a maximum of 256 bytes. 
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7.4.3 FLG - Key Options 


The key options (FLG) field defines optional characteristics of the 
key represented by the XAB. These characteristics are: 


1. Duplicate key values are allowed. 
2. Key values can change. 
3. Null key value. 


You use the XS$FLG macro to initialize the FLG field at assembly-time. 
Its format is: 


XSFLG option[!option...] 
where 


option is a symbolic value specifying a characteristic of 
the key field defined by the Extended Attribute 
Block. The following values may be specified: 


XBS$CHG indicates that the associated key within 
any record can be changed by a program 
during a $UPDATE operation. This option 
can be specified only for alternate keys 
and only in conjunction with XBS$DUP. 


XBSDUP indicates that records within the file 
may have the same values within the key 
field associated with this XAB. 


The allowed combinations of XBSCHG and 
XBSDUP depend on the type of key (i.e., 
primary or alternate) represented by the 
extended attribute block. Table 7-3 
summarizes these combinations. 


XBSNUL indicates that the NUL field of this XAB 
contains a null key value. You can 
specify this characteristic only for 
alternate keys. 


Table 7-3 
Key Option Combinations 


Combination 


CHANGE CHANGE NO CHANGE NO CHANGE 
+ 


+ + + 
DUPLICATES NO DUPLICATES DUPLICATES NO DUPLICATES 


Primary | Error Allowed . Default 


Alternate Default Allowed Allowed 


The assembly-time default values for the FLG field depend on the’ type 
of key (i.e., primary or alternate) defined by the XAB. The defaults 
for a primary key are: 
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1. Duplicate key values are not allowed. 
2. Key values cannot change. 
3. No null key value. 
The defaults for alternate keys are: 
1. Duplicate key values allowed. 
2. Key values can change. 
3. No null key value. 


The symbolic values you specify using the X$FLG assembly-time macro or 
the S$STORE runtime macro are mapped into bit settings in the FLG. 
field. When a bit is set, it means’ that the corresponding 
characteristic was specified (e.g., key values can change or duplicate 
key values allowed or null key value defined). Conversely, when a bit 
is zero, it means that the corresponding characteristic is not defined 
for the key (e.g., key values cannot change, or duplicate keys not 
allowed or null key not defined). Both the XSFLG and the S$STORE macro 
affect the entire FLG field, setting those bits specified and clearing 
to zero those not specified. Therefore, when defining the 
characteristics of a key, you should specify exactly what you want the 
field to contain, expressing bit settings as symbolic values. Any 
symbolic values you omit will result in a zero in the corresponding 
bit position. As examples, consider the following: 


1. KEYDEF: XABSB XBSKEY 


X$SFLG XBSDUP! XBSNUL 


XABSE 


2. KEYDEF: XABSB XBSKEY 


XSFLG XBSNUL 


XABSE 
3. STORE #0,FLG,R3 


In the first example, the user specifies that duplicate keys are 
allowed, a null key value is defined, and (through the absence of 
XBSCHG) that key values cannot change. In the second example, the 
user specifies that a null key value is defined but duplicate key 
values are not permitted and key values cannot change. In the _ third 
example, the user sets the FLG field to indicate that duplicate key 
values are not permitted, key values cannot change, and no null key is 
defined. 
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7.4.4 IAN - Area Number for Index Buckets 


You set a value in the area number for index buckets (IAN) field only 
1f both of the following are true: 


l. You are creating a new indexed file. 


2. You are using allocation XABs (refer to Section 7.6) to 
control the placement and structure of the file. 


If both of the above are true, then you use the IAN field to assign 
the buckets of the index level of the index defined by this XAB to one 
of the areas defined by an allocation XAB. 


When the key definition XAB describes the primary key, the index level 
of the index consists of all levels of the tree-structured primary 
index down to and including the level containing pointers to the user 
data records themselves. When, however, the xXAB describes an 
alternate key, the index level consists of all levels of the 
tree-structured alternate index down to, but not including, the level 
containing buckets in which RMS-1l maintains pointer arrays describing 
the user data records (refer to the LAN field description for an 
additional facility in index bucket assignment). 


The XSIAN macro allows you to initialize the IAN field at 
assembly-time. Its format is: 


XSIAN aid 


where 
aid is a numeric value from 0 to 254 representing an area 
identification number contained in the AID field of an 
allocation XAB present in the same chain. The 


assembly-time default is 0 (i.e., area 0). 


In the following example, the user assigns the index level of the key 
defined by the XAB called KEYDEF to area 2. 


AREA2: XABS$B XBSALL 


KEYDEF: XAB$B XBS$KEY 
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7.4.5 IFL - Index Bucket Fill Size 


At SCREATE time, you can use the IFL field to specify how many bytes 
you want used in each index level bucket of the associated index. By 
specifying less than the total bucket size, you indicate that the 
index buckets are not to be completely filled but are to contain some 
amount of free space. At runtime, RMS-1l adheres to the fill size 
specified at $CREATE time only if the RBSLOA value is present in the 
record processing options (ROP) field of the RAB. 


When the key definition XAB describes the primary key, the IFL field 
describes space in buckets in all levels of the tree-structured 
primary index down to and including the level containing pointers’ to 
the user data records themselves. When the XAB describes an alternate 
key, IFL applies to all levels of the tree-structured alternate index 
down to, but not including, the level containing buckets in which 
RMS-11 maintains pointer arrays describing the user data records. 


You may want to use the facility provided by the IFL field (and _ the 
Similar facility provided by the DFL field, described in Section 
7.4.2) in the following situation: If you expect to perform numerous 
SPUT and S$UPDATE operations on the file after it has been initially 
populated, you can minimize the resultant movement of index entries 
(known as bucket splitting) by specifying a less than maximum bucket 
fill size at SCREATE time. To use the free space thereby reserved in 
the index buckets, programs that perform $PUT or SUPDATE operations on 
the file should not place, at S$CONNECT time, the value RBS$LOA in the 
ROP field of the RAB. . 


You can initialize the IFL field at assembly-time with the xXSIFL 
macro. The format of the XSIFL macro is as follows: 


XSIFL space 
where 


space is a numeric value representing the maximum number 
of bytes to be used in the index buckets. The 
assembly-time default is 0, which is’ interpreted 
at runtime by RMS-11l as meaning the bucket size in 
bytes (i.e., no unused space). 


The following is an example of the XSIFL macro: 


KEYDEF: XABSB_ XBSKEY 


XSIFL 300 


XABSE 


In this example, the user specifies that 300 bytes of each index 
bucket are to be used. 
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7.4.6 KNM - Key Name Address 


The Key Name Address (KNM) field can contain the address of a 
32-character ASCII string. When you are defining a key, you can 
associate any 32-character string you choose with the key field 
represented by the XAB. RMS-1l never examines this character string 
but retains it in the file as part of the key definition information. 


You can initialize the KNM field at assembly-time with the XS$KNM 
Macro. Its format is: 


XSKNM address 
where 


address is the symbolic address of a buffer. This’ buffer 
should always be at least 32 bytes in length. A 
value of 0 in this field indicates that no _ key 
name is defined (S$CREATE) or is to be displayed 
(SOPEN or $DISPLAY) . 


7.4.7 LAN - Lowest Index Level Area Number 


You set a value in the LAN field only when both of the following are 
true: 


1. You are creating a new indexed file. 


2. You are using allocation XABs (refer to Section 7.6) to 
control the placement and structure of the file. 


If both of the above are true, then the LAN field allows you _ to 
separate the lowest level of the index from all higher levels by 
specifying a different area number than that specified by the IAN 
field. However, the bucket size of the area specified by the LAN 
field must be the same as that of the area identified by the IAN 
field. | 


You can initialize the LAN field at assembly-time with the XSLAN 
macro: 


XSLAN aid 
where 


aid is a numeric value from 0 to 254. A value of 0 
indicates that the lowest level of the index is to 
occupy the same area as the remainder of the index. 
Values from 1 to 254 represent an area identification 
number contained in the AID field of an allocation XAB. 
The assembly-time default is 0. 


7.4.8 NUL - Null Key Value 


The NUL field can contain any user-selected character value. When you 
create an indexed file, however, RMS-1l examines and_ saves the 
contents of this field only if the value XBSNUL is present in the FLG 
field of the block. Further, the null key facility is available only 
for Extended Attribute Blocks that define an alternate key. 
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When writing a record into an indexed file, RMS-1l normally updates 
all indexes of the file to reflect the values found in the 
corresponding key fields of the record. However, if a null key value 
is defined for a particular alternate key, RMS-1l examines the 
contents of the key field in the’ record. If this field consists 
solely of the null key characters specified in the NUL field of the 
XAB that defined the key at $CREATE time, RMS-11 will not make an 
entry in the associated alternate index for the record. 


The XSNUL macro can be used to initialize the NUL field at 
assembly-time. The format of this macro is as follows: 


XSNUL value 
where 

value is any user-selected character value. 
The following are two examples of the XSNUL macro: 


l. KEYDEF: XABSB XBSKEY 


XSFLG XBSNUL 
X$NUL <'Z> 


XABSE 


2. KEYDEF: XABSB XBSKEY 


XSFLG XBSNUL 
XSNUL <*0177> 


XABSE 


In the first example, the user specifies that any record containing 
all Z's in the key field defined by the current XAB is not to have an 
entry made for it in the associated alternate index. In the second 
example, the user specifies the same action but the null key value is 
the ASCII character DEL. 


7.4.9 POS - Key Position 


In combination with the SIZ field, the POS field defines the location 
of the key within each record of the file. The POS field is eight 
words in length because two types of keys can be defined -- simple 
keys and segmented keys. 


A simple key is a single string of contiguous bytes in the record. 
The first word of the POS field specifies the starting position of the 
string and the remaining words contain zeros. 


A segmented key consists of two to eight strings of bytes in the 


record. Each individual string (segment) is a set of contiguous 
bytes, but the strings need not be contiguous with each other, nor 
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need they be in any particular order. Each successive word of the POS 
field specifies the starting position of one of the segments. When 
processing records that contain segmented keys, RMS-1l1 treats the 
individual segments of the key as a single, logically contiguous 
string beginning with the first segment and ending with the last. 


The X$POS macro can be used to initialize the POS field at 
assembly-time. The format of this macro for simple keys is as 
follows: 


X$POS position 
where 


position is a numeric value representing the starting 
position of the key within each record. The first 
byte of a record is represented by a value of 0, 
the second by a value of 1, etc. 


For segmented keys, the format of the X$POS macro is as follows: 
X$POS <pos0,posl1[,pos2...,pos7]> 
where 


pos0,posl,etc. are numeric values representing starting positions 
of each segment of the segmented key. Up to eight 
values can be specified. It is not necessary that 
the list of values represent ascending byte 
positions in the record. To define a segmented 
key, the POS field and the SIZ field must contain 
an equal number of successive values. 


Three examples of the X$POS macro follow: 


l. KEYDEF: XABSB XBSKEY 


XSPOS 0 


XABSE 


2. KEYDEF: XAB$B_ XBSKEY 


XABSE 


3. KEYDEF: XABSB XBSKEY 


X$SPOS <19,0,13,28> 
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In the first example, the user defines a simple key that begins in the 
first byte of each record. The second example shows the specification 
of a simple key beginning in the ninth byte of each record. To 
complete the definition of these simple keys, the user must establish 
a corresponding value in the key size (SIZ) field of the block. In 
the third example, the user specifies a segmented key. The first 
segment of the key begins in the twentieth byte, the second segment 
begins in the first byte, the third segment in the fourteenth byte, 
and the fourth segment in the twenty-ninth byte. To complete’ the 
definition of this segmented key, the user must establish four values 
for the size field (SIZ) corresponding to these four segment 
positions. 


7.4.10 REF - Key of Reference 


The key of reference (REF) field identifies which key (i.e., primary, 
first alternate, second alternate, etc.) is defined by the XAB. 


The XS$REF macro allows you to initialize the REF field at 
assembly-time. The format of this macro is as follows: 


XSREF value 
where 


value is a numeric value, in the range of 0 to 254, 
indicating which key is represented by the current 
block. A value of 0 indicates the primary key, 1 
indicates the first alternate key, etc. The 
assembly-time default value for the REF field is 
zero (i.e., primary key). 


The following are two examples of the xXSREF macro, showing the 
specification of a primary key in the first case, and the 
specification of a third alternate key in the second case. 


1. KEYDEF: XABSB_ XBSKEY 


XSREF 0 


XABSE 


2. KEYDEF: XABSB' XBSKEY 
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7.4.11 RVB - Root Virtual Block Number 


When a key definition XAB is present during an SOPEN or S$DISPLAY 
operation, RMS-l1l sets RVB to the number of the virtual block of the 
file that contains the root of the index for the key described by the 
XAB. 


The key size (SIZ) field specifies the length of the key whose 
Starting position is contained in the POS field of the same block. 


The xXS$SIZ macro can be used to initialize the SIZ field at 
assembly-time. 


For simple keys, the format of the X$SIZ macro is as follows: 
X$SIZ size 
where 


size is a numeric value representing the length (in 
bytes) of the key defined by the block. Allowed 
values for the SIZ field are 1 to 255. 


For segmented keys, the format of the X$SIZ macro is as follows: 
XSSIZ <size0,sizel [,size2...size7]> 
where 


size0,sizel,etc. are numeric values representing the length of 
each segment of the segmented key. Up to eight 
values can be specified. The total size 
specified must be less than 256. To define a 
segmented key, you must provide an equal number 
of values for the SIZ and POS fields of the 
block. For example, the first value specified 
on an xXS$POS macro will be combined with the 
first value on an xX$SI2Z macro to define _ the 
location and length of the first segment of the 
segmented key, etc. 


Two examples of the XS$SIZ macro follow: 


1. KEYDEF: XABSB XBSKEY 


X$SIZ_ 8 


XABSE 


2. KEYDEF: XABSB XBSKEY 


X$SIZ <8,2,5,32> 
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In the first example, the user specifies a key length of 8 bytes. In 
the second example, the user specifies the lengths of the four 
segments of a segmented key. Assume that the following initialization 
Macro is also present for the same block: 


X$POS <19,0,13,28> 


The following is the full definition of the segmented key: 


Start Position Length 
20th byte 8 bytes 
lst byte 2 bytes 
14th byte 5 bytes 
29th byte 32 bytes 

Total Key Length = 47 bytes 


7.5 FILE PROTECTION SPECIFICATION EXTENDED ATTRIBUTE BLOCK 


A file protection specification Extended Attribute Block contains 
protection information for the associated file. When you create a 
file, you can use this type of XAB to explicitly assign protection 
codes. When you open an existing file, you can use this type of XAB 
to obtain the protection codes specified when the file was created. 
Table 7~4 describes the fields of this type of XAB. 


Table 7-4 
File Protection Specification XAB Fields 


Code field contains the value 
XBS$ PRO. 


Next XAB. 

Programmer number portion of 
owner's user identification code 
(UIC). 


Project number portion of owner's 
user identification code (UIC). 


System dependent file protection 
value. . 


The following subsections describe the fields listed in Table 7-4 that 
are unique to the file protection specification XAB. 
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7.5.1 PRG - Programmer Number 


The PRG field contains the programmer number portion of the file 
owner's user identification code. 


The xXSPRG macro can be used to initialize the PRG field at 
assembly-time. The format of the X$PRG macro is as follows: 


XSPRG number 


where 
number is a numeric value representing a programmer 
number. The specified value must range from 1 to 
255% 


The following is an example of the XS$PRG macro: 


PRODEF: XABSB XB$PRO 


XSPRG 11 


7.5.2 PRJ - Project Number 


The PRJ field contains the project number portion of the file owner's 
user identification code. 


The X$PRJ macro allows you to initialize the PRJ field at 
assembly-time. The X$PRJ macro takes the following form: 


XSPRJ number 
where 


number is a numeric value representing a project number. 
The specified value must range from 1 to 255. 


The following is an example of the X$PRJ macro: 


PRODEF: XABS$B XBS$PRO 


X$PRG 211 
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7.5.3 PRO - System File Protection Value 


The system file protection value (PRO) field identifies the file 
access privileges of four classes of users: 


1. Group - the class of users with the same project number as 
contained in the PRJ field of the current block. 

2. Owner - the owner of the file. 

3. System - users executing under a privileged user 


identification code. 


4. World - all users not within the group, owner, and system 
categories. 


The format of the one-word PRO field is as follows: 


Bits 15 12 11 8 7 4 


3 0 
WORLD GROUP owner | SYSTEM 


Figure 7-1 Format of PRO Field 


Each of the four categories above has four bits; each bit has the 
following meaning with respect to file access: 


Bit ‘3 2 1 0 


DELETE EXTEND WRITE READ 


Figure 7-2 File Access Bits 


A bit value of zero (0) indicates that the respective type of access 
to the file is to be allowed; a bit value of one (1) indicates that 
the respective type of access to the file is to be denied. 


The X$PRO macro initializes the PRO field at assembly-time. Its 
format is: 


X$ PRO protect 
where 


protect iS a numeric value representing the desired 
encoding for the l-word field. The default radix 
for this value is decimal. Use of the MACRO-11 
octal radix unary operator will facilitate the 
setting of this field. 
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In the following example, the user grants full access rights to the 
system and owner and restricts the group and world classes to read 
only privileges. 


XSPRO <~0167000> 


7.6 ALLOCATION EXTENDED ATTRIBUTE BLOCKS 


Each allocation XAB describes one area of a file. An area iS a 
portion of a file that is treated as a single entity for the purposes 
of: 


- initial allocation 
- extension 

- placement control 
- bucket size 


Only indexed files can contain more than one area. Multiple areas, if 
present, in an indexed file are consecutively numbered beginning with 
0. Sequential and relative files are always composed of a single area 
(area 0). 


In allowing you to define file areas, allocation XABs’' serve the 
following two purposes: 


1. They allow you to control the physical placement of a file 
(of any organization) on a volume. 


2. They allow you to control the internal structure of an 
indexed file. 


To control the physical placement of a file on a volume, you provide 
one (for any type of file) or more (for indexed files only) allocation 
XABsS linked to the FAB you use to create the file. Within each 
allocation XAB_ are two fields -- alignment (ALN) and location (LOC). 
If you set the symbolic value XBSLBN in the ALN field, and a numeric 
value in the LOC field, RMS-11 considers the contents of the LOC field 
as a logical block number on the’ volume. RMS-11 then attempts. to 
allocate the initial virtual block of the area represented by the XAB 
at the specified logical block. The same allocation XAB allows you to 
specify the initial allocation size (ALQ) and, for indexed files only, 
a default extension quantity (DEQ) for the area. 


Either with or without the placement control facility, you can _ use 
allocation XABs to control the internal structure of an indexed file. 
You can define multiple areas within such a file, assign the index and 
data levels associated with keys to particular areas, and vary the 
size of buckets on a per-area basis. Indeed, varying the size of 
buckets among different areas of an indexed file can be the primary 
motivation for your use of allocation XABs. For example, if your 
indexed file will contain large data records, you may want 
particularly large buckets for the data level of the primary key. 
However, you may not want to use the same size buckets for the index 
levels of the key. Conversely, for another indexed file, you might 
want index level buckets that are larger than data level buckets in 
order to minimize the number of index levels that RMS-1l must traverse 
to access any record. 


7-19 


EXTENDED ATTRIBUTE BLOCKS 


Both facilities provided by allocation XABs -- placement control and 
indexed file structuring -- are completely optional. If you do not 
require either of these facilities, you do not need allocation XABs. 
In the absence of allocation XABs, RMS-1ll provides the following 
defaults: 


1. When you create a new file (of any organization), RMS-11 
allocates a single area (implicitly, area 0) to the file. 
The initial size of this area is specified in the ALQ field 
of the FAB and the file-level default extension quantity in 
the DEQ field of the FAB. The physical placement of the file 
on the volume is completely under the control of the host 
operating system. 


2. For an indexed file, the absence of allocation XABs_ when 
creating a file results in-the allocation of a single area 
(again, area 0) for the entire file and the use of a _ single 
bucket size for the entire file. 


When the preceding defaults are unsuitable for a particular file, you 
will need allocation XABs in your program. 


Once you create (via SCREATE) a particular file using allocation XABs, 
you can also use such XABs with the SEXTEND, SOPEN, and S$DISPLAY macro 
calls. Table 7-5 lists the fields in an allocation XAB. The 


subsections that follow describe the function of each field with each 
of the macro calls. 


Table 7-5 
Allocation XAB Fields 


1 byte Area identification number. 
1 byte Alignment boundary type. 
2 words Allocation quantity. 


1 byte Allocation option. 
(bit string) 


byte Bucket size. 


byte Code field. Contains the 
value XBSALL. 


word Default area extension quantity. 


words Allocation starting point. 


word Next XAB. 


word Relative volume number. 
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7.6.1 AID - Area Identification Number 


The area identification (AID) field identifies the area of the file 
described by the allocation XAB. You are always responsible for the 
contents of this field. It is never set by RMS-1ll. Rather, RMS-1l 
uses this field to: 


1. Check the sequencing of allocation XABs in an XAB chain. For 
all operations (i.e., $CREATE, S$EXTEND, S$OPEN, $DISPLAY), 
allocation XABs in an XAB chain must appear in ascending 
order, based on the contents of the AID field in each. 


2. Identify the target area for a specific operation (e.g., 
SCREATE, SEXTEND, etc.). 


You can initialize the AID field at assembly-time with the xXS$AID 
macro. Its format is: 


XSAID area 
where 


area is a numeric value indicating which area of the file is 
described by the current block. Area identification 
numbers range from 0 to 254. If the organization of 
the file is sequential or relative, only a single 
allocation XAB can be used for any operation and its 
AID field must contain 0. The assembly-time default 
for this field is 0. 


In the following example, the user establishes an allocation XAB_ for 
area 1 of an indexed file: 


AR1: XABSB XBSALL 


7.6.2 ALN - Alignment Boundary Type 


The alignment boundary type (ALN) field specifies the type of 
alignment requested for the area described by the block. If you 
require placement control over the initial allocation ($CREATE) or 
explicit extension ($EXTEND) of the area, you use this field to 
specify whether the LOC field contains a logical block number or a 
virtual block number. If you do not wish to exercise placement 
control during a $EXTEND or S$CREATE operation, you set this field 
equal to zero. 


When allocation XABs are present during a SOPEN or $DISPLAY operation, 
RMS-1l sets the ALN field equal to the value specified for the 
corresponding area when the file was created. 


You can use the xXSALN macro to initialize the ALN field at 
assembly-time. Its format is: 


XSALN type 


EXTENDED ATTRIBUTE BLOCKS 


where 


type is a symbolic value or 0. One of the _ following 
symbolic values can be specified: 


XBSLBN - align area (or extension to area) on or near 
logical block described by LOC field. 


XBSVBN - perform allocation aS near as possible to 
the virtual block described by LOC field. 
If LOC contains 0, RMS-11 will allocate 
Space aS near as possible to the current 
high virtual block of the file. If the AID 
field of the block specifies area 0, the 
value XBSVBN is invalid during a S$CREATE 
operation. 


RMS-11 interprets a value of 0 in the ALN field as 
meaning no placement control is being exercised by the 
user. The assembly-time default is 0. 


In the following example, the user indicates that no placement control 
is described by the current allocation XAB. 


AR1: XABSB XBSALL 


XABSE 


7.6.3 ALQ - Allocation Quantity 


The allocation quantity (ALQ) field specifies the number of virtual 
blocks in the initial allocation of the area (when the allocation XAB 
is used with the SCREATE operation) or the number of virtual blocks by 
which the area is to be extended (when the block is part of a S$EXTEND 
operation). For both operations, the value you specify in this field 
overrides the contents of the ALQ field in the FAB. RMS-11 neither 
examines nor sets this field during S$OPEN and $DISPLAY operations. 


The XSALQ macro allows you initialize the ALQ field in this block at 
assembly-time. The format of this macro is as follows: 


XSALQ quantity 
where 


quantity iS a numeric value in the range of 0O to 16,777,215 
representing a number of virtual blocks. If, during a 
SCREATE operation, the user-specified quantity in the 
ALQ field for allocation area 0 is less than the number 
required to store necessary file attributes, RMS-11 
ignores the user-specified value and allocates a 
sufficient number of virtual blocks. 


EXTENDED ATTRIBUTE BLOCKS 


In the following example of the X$ALQ macro, the user specifies that 
400 virtual blocks are to be allocated to the area described by the 
block: . 


AR1: XABSB.  XBSALL 


XSALQ 400 


XABSE 


7.6.4 AOP - Allocation Options 


The allocation options (AOP) field allows you to qualify the action 
RMS-11 is to perform when the block is present during a $CREATE or 
SEXTEND operation. For SOPEN and $DISPLAY operations, RMS-1l_ returns 
into this field the options specified when the area was created (via 
SCREATE). 


The XSAOP macro can be used to initialize the AOP field at 
assembly-time. Its format is: 


XSAOP option[!option] 
where 


option is a symbolic value representing an option to be 
applied during a $CREATE or $EXTEND operation. You can 
specify either or both of the following: 


XBSHRD - Hard request. This option should be 
specified only if the ALN field contains the 
value XBSLBN. RMS-1l returns an error’ code 
if the initial allocation (S$CREATE) or 
extension (SEXTEND) of the area cannot be 
aligned on the logical block specified by 
the LOC field. The default is to perform 
the allocation as close as possible to the 
requested alignment. 


XBSCTG - Contiguous allocation requested. The 
assembly-time default is non-contiguous. 


In the following example of the XSAOP macro, the user specifies a hard 
request for a contiguous allocation: 


AR1: XABSB XBSALL 


XSAOP XBSCTG!XBSHRD 


7-23 
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7.6.5 BKZ - Bucket Size 


The BKZ field specifies the size of the buckets in the area described 
by the allocation XAB. This field is used for indexed files only. 
During a $CREATE operation, the value you specify in this field 
supersedes the contents of the BKS field in the FAB. During SOPEN and 
‘$DISPLAY operations, RMS-1ll returns into this field the value 
specified when the area was created. The primary purpose of this 
field is to allow you to vary the size of buckets among the multiple 
areas of an indexed file. 


The X$BKZ macro allows you to initialize the BKZ field at 
assembly-time. The format of this macro is as follows: 


XSBKZ bucket-size 
where 


bucket-size is a numeric value, in the range of 0 to 32, 
representing the number of virtual blocks 
contained in each bucket in the area of the file. 
The assembly-time default is 0. RMS-1l interprets 
a value of 0 as identical to l. 


The following is an example of the XS$BKZ macro showing the 
specification of four virtual blocks per bucket: 


AR1: XABSB 


XSBKZ 4 


7.6.6 DEQ - Default Area Extension Quantity 


The default area extension quantity (DEQ) field applies to indexed 
files only. It specifies the number of virtual blocks to be used when 
RMS-11 must automatically extend the area described by the XAB. This 
automatic extension occurs whenever your program attempts a $PUT or 
SUPDATE operation that cannot be accommodated within the space 
currently allocated to the area. 


During a $CREATE operation, RMS-11 examines the value you specified in 
this field. If this value iS nonzero, RMS-1ll saves it as the default 
extension quantity for the area defined by the XAB. If, however, the 
DEQ field in this’ block is zero, RMS-11 saves the FAB's DEQ as the 
default extension quantity for the area defined by the XAB. 


The DEQ field in the allocation XAB is neither examined nor set during 
a S$EXTEND operation. During a S$OPEN or $DISPLAY operation, however, 
RMS-11 returns into this field the value specified when the area was 
created. 


You can use the X$DEQ macro to initialize the DEQ field of an 
allocation XAB at assembly-time. The format of this macro is: 


XSDEQ quantity 


EXTENDED ATTRIBUTE BLOCKS 


where 


quantity iS a numeric value representing a number of virtual 
blocks. This number must be in the range of from 0 to 
65,535. The quantity you specify should be a multiple 
of the area's bucket size. The assembly-time default 
is 0. 


In the following example, the user specifies that, when automatic 
extension iS necessary, RMS-1l is to extend the area by 80 virtual 
blocks. 


AR1: XABSB 


X$SDEQ 80 


XABSE 


7.6.7 LOC - Allocation Starting Point 


The allocation starting point (LOC) field is used by RMS-1l only 
during S$CREATE and SEXTEND operations. Further, the contents of this 
field are ignored during such operations if the ALN field of the’ same 
block is zero. When, however, the ALN field contains XBSLBN, RMS-11l 
interprets the contents of LOC as the starting logical block number on 
the volume for the initial allocation (SCREATE) or extension ($EXTEND) 
of the area. The ALQ field of the same block contains the number of 
blocks to be allocated and the AOP field can optionally specify 
(XBSHRD) that the allocation must begin with the specified logical 
block. 


When the ALN field contains XBSVBN during a S$CREATE or $EXTEND 
operation, RMS-1l interprets the contents of LOC as a virtual block 
number within the file. For $CREATE operations, LOC must _ contain 
zeroes since no virtual blocks as yet exist in the file. However, 
during S$EXTEND operations, LOC can contain the number of a virtual 
block in the file near which the extension to the area is to be 
allocated. Again, you use the ALQ field to specify the size of the 
extension. Note, however, that the allocation options (AOP) field 
cannot contain XBSHRD. 


During S$OPEN and $DISPLAY operations, RMS-1ll neither sets nor examines 
the LOC field. 


The xXSLOC macro allows you to initialize the LOC field at 
assembly-time. Its format is: 


X$LOC number 
where 
number is a numeric value interpreted as follows: 
l. If ALN contains XBSLBN, the specified number is the 
Starting logical block for the allocation. The 


specified number may vary from 0 to the maximum 
number of blocks on the volume. 


EXTENDED ATTRIBUTE BLOCKS 


2. If ALN contains XBS$SVBN, the specified number is a 
virtual block within the file. The specified 
number may vary from 0 to the number of virtual 
blocks in the file. A value of 0 (assembly-time 
default) implies that allocation should occur as 
near as possible to the current end of file. 


The following is an example of the X$LOC macro: 


AR]: XABSB 


X$AOP XBSHRD 
XSALN XBSLBN 
X$LOC 1024 


XABSE 


In this example, the user specifies that allocation of an extent for 
the area represented by the XAB must begin on logical block number 
1024. 


7.6.8 VOL - Relative Volume Number 


The relative volume number (VOL) field must contain 0. The 
assembly-time default for this field is 0. 


7.7 SUMMARY EXTENDED ATTRIBUTE BLOCK 


The summary XAB allows you to determine the number of keys defined for 
an existing indexed file and/or the number of allocation areas defined 
for an existing file. 


You never use this type of XAB with a SCREATE macro call. However, a 
summary XAB can be associated with a FAB at the time a SOPEN or 
SDISPLAY macro call is issued. The presence of this XAB during these 
macro calls allows RMS-11 to return to your program the total number 
of keys and allocation areas defined when the file was created. 


Table 7-6 describes the fields of a summary XAB. 


Table 7-6 
Summary XAB Fields 


COD Code field. Contains the value 
XBSSUM. 


Number of allocation areas defined 
for the file. 


Number of keys defined for the 
file. 


Next XAB. 


CHAPTER 8 


THE NAME BLOCK 


The Name Block is an optional structure. After a successful S$CREATE, 
SOPEN, or S$ERASE macro call, a location described by this block 
contains the full file specification resulting from RMS-1l's merger of 
the default file name string (described by the DNA and DNS fields of 
the associated FAB) with the primary name string (described by the FNA 
and FNS fields of the associated FAB) and system defaults. You 
indicate that this service is desired by assuring that the NAM field 
of the FAB contains the address of a Name Block at the time a S$CREATE, 
SOPEN, or $ERASE macro is issued. 


The following subsections describe the allocation of a Name Block and 
assembly-time initialization macros for fields in the block. 


8.1 ALLOCATING A NAME BLOCK 


The NAMSB macro allocates space for a Name Block and delimits' the 
beginning of an optional sequence of assembly-time initialization 
macros for the fields of the block. 


The format of the NAMSB macro is as follows: 
label:NAMSB 
where 


label is a user-specified symbol that names this 
particular Name Block. You must ensure that the 
address assigned to this label is word-aligned. 
Therefore, a .EVEN directive should immediately 
precede the NAMSB macro. 


The NAMSE macro delimits the end of the optional sequence of 
assembly-time initialization macros initiated by NAMS$B and stores any 
specified values in the appropriate fields of the block. This macro 
must always appear subsequent to an associated NAMSB macro, even when 
no intervening initialization macros are coded. 


The NAMSE macro takes the following form: 
NAMSE 


The following example shows the allocation of a Name Block called 
FNAME : 


- EVEN 
FNAME: NAMSB 
NAMSE 
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8.2 FIELDS IN THE NAME BLOCK 


Table 8-1 summarizes the fields in a Name Block. 


Table 8-1 
Name Block Fields 


Expanded string address 


Expanded string length 
Expanded string size 


The subsections that follow describe the fields listed in Table 8-1. 


8.2.1 ESA - Expanded String Address 


The expanded string address (ESA) field contains the address of a 
user-allocated buffer. Following a S$OPEN, S$CREATE, or SERASE macro 
call, RMS-11l places in this buffer the file specification string 
resulting from the application of default information (provided by the 
default name string of the FAB and system defaults) to the original 
file string (file name string of the FAB). The ESA buffer must be 
present if the block itself is input to an operation (i.e., the NAM 
field of the FAB is nonzero). 


The NSESA macro allows you to initialize the ESA field at 
assembly-time. The following is the format of the NSESA macro: 


NSESA address 
where 


address is the symbolic address of a buffer in the user 
program. 


The following is an example of the NSESA macro: 


NAMBUF: .BLKB 32. 


FNAME: NAMSB 


NSESA NAMBUF 
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8.2.2 ESL - Expanded String Length 
The expanded string length (ESL) field is set by RMS-1ll after a S$OPEN, 


SCREATE, or SERASE macro call. This field contains the actual length 
of the expanded file specification whose address is in the ESA field. 


8.2.3 ESS - Expanded String Size 


The expanded string size (ESS) field contains the size of the 
user-allocated buffer whose address is in the ESA field of the block. 


You can initialize the ESS field at assembly-time with the NSESS 
Macro. The format of the NSESS macro is as follows: 


NSESS size 
where 
size is a numeric value representing the size (in 
bytes) of the buffer whose address is in the ESA 
field. The specified value must range from 1 to 
255. 


In the following example, the user specifies an expanded string area 
of 32 bytes: 


FNAME: NAMSB 
NSESA NAMBUF 
NSESS 32 


NAMSE 


CHAPTER 9 


PERFORMING FILE AND RECORD OPERATIONS 


This chapter describes the RMS-1ll macros used to access and manipulate 
files and records within files. 


As described in Chapter 2, file and record processing macros. in 
combination with user control blocks form the runtime program 
interface with RMS-ll. The primary argument of a file processing 
Macro call is the address of a File Access Block. The primary 
argument of a record processing macro call is the address of a _ Record 
Access’ Block. Certain fields within these blocks must contain 
appropriate values at the time a particular file or record processing 
macro call is issued. Following such macro calls, RMS-1ll returns 
information to your program within fields of the same control block. 
The detailed descriptions of file and record processing macros in this 
chapter, therefore, list all control block fields used as input to a 
macro call and every field that may contain information returned to 
your program by RMS~-11l. 


The remainder of this chapter is divided into three sections: 


1. File and record operation macro conventions (i.e., macro 
formats, the RMS-ll calling sequence, completion routines, 
control block field usage, and status codes). 


2. Performing file operations (i.e., $CREATE, S$OPEN, S$DISPLAY, 
SERASE, SEXTEND, $CLOSE). 


3. Performing record operations (i.e., record access streams, 
record operations and file sharing, current context of record 
operations, synchronous and asynchronous operations, 
accessing records, and record operation macros). 


NOTE 


When RMS-1l is executing, asynchronous 
system traps (ASTs) are disabled. When 
RMS-l1l returns to your program, ASTs are 
enabled. 


9.1 FILE AND RECORD OPERATION MACRO CONVENTIONS 


While differing in function, file and record operation macros have the 
same general format. Furthermore, each macro call for an RMS-11l 
service requires the establishment of a standard calling sequence. 
Within this calling sequence, you can optionally specify the addresses 
of completion routines. 
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Before issuing the actual file or record operation macro call, your 
program must ensure that the control block (i.e., FAB or RAB) contains 
appropriate values in the fields that will be examined by RMS-11. 
Following execution of the macro call, your program should examine the 
status code returned by RMS-1ll in the control block to ascertain the 
success or reason for failure of the operation. The following 
subsections, therefore, describe: 


The format of file and record processing macros 
The RMS-11 calling sequence 

Completion routine conventions 

Control block field usage 

Status codes 


9.1.1 Format of File and Record Operation Macros 


You can code file and record operation macros in either of the 
following two formats: 


l. label:S$macro 


or 
2. label:S$macro block[,error[,success] ] 
where 

label is an optional user-defined symbol referring to the 
macro. 

Smacro is one of the file or record operation macros described 
in this chapter. 

block is the address of a File Access Block (for file 
operations) or a Record Access’ Block (for record 
operations.) 

error is the address of a user completion routine to _ be 


called if the requested operation fails. 


success is the address of a user completion routine to be 
called if the requested operation completes 
successfully. This argument is ignored for file 
processing macro calls. 


In the second format, the presence of arguments causes the macro 
expansion to build an argument list on your program's stack. In the 
first format above, however, no arguments appear following the macro 
name. In this format, therefore, you must create the argument list in 
your program. The following subsection describes this process. 


NOTE 


The first format of RMS-1l file and 
record operation macros (i.e., without 
an argument list) generates less code 
and uses less stack space than _ the 
second format. 
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9.1.2 The RMS-1l1 Calling Sequence 
At the time an RMS-1l routine is called, general register R5 must 


contain the address of a word-aligned formatted argument list. Figure 
9-1 shows the format of this list: 


ARGUMENT. COUNT 


Figure 9-1 Argument List Format 


~=——R5 


RMS-11 interprets the fields within the argument list as follows: 


Argument Count is a binary value from 1 to 3. representing 
the number of arguments present in the 
argument list. This count field must equal 1 
if the user does not specify completion 
routine addresses. 


Block Address is the address of a File Access Block (for 
file operations) or a Record Access Block 
(for record operations). 


Error Address is the address of a user completion routine 
to be called if the requested operation 
fails. 

Success Address is the address of a user completion routine 
to be called if the requested operation 
completes successfully. This argument is 


ignored for file processing macro calls. 


The preceding argument list is automatically generated whenever you 
specify a file or record processing macro with arguments. When 
specifying these macros without arguments, your program must construct 
the argument list. For example, if you want to read a record from a 
file and specify both an error and a success completion routine, the 
equivalent of the following sequence must be coded: 


MOV #LIST,R5 ;ADDRESS OF ARGUMENT 
:LIST TO REGISTER 5 
SGET :RECORD PROCESSING MACRO 


7;TO READ A RECORD 


LIST: .WORD 3 ;NUMBER OF ARGUMENTS 
-WORD INRAB ;RECORD ACCESS BLOCK ADDRESS 
«WORD ERR1 7ERROR ROUTINE ADDRESS 
-WORD succl 7;SUCCESS ROUTINE ADDRESS 


If you wanted to specify a success routine without specifying an error 
routine, you would use the following code for the argument list: 


LIST: .WORD 3 ;NUMBER OF ARGUMENTS 
-WORD INRAB ;RECORD ACCESS BLOCK ADDRESS 
- WORD ~l 7-1 MEANS NO ERROR ROUTINE 
- WORD succl ;SUCCESS ROUTINE ADDRESS 
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If neither a success nor an error routine is specified, the argument 
list is constructed as follows: 


LIST: .WORD 1 - sNUMBER OF ARGUMENTS 
. WORD INRAB ;RECORD ACCESS BLOCK ADDRESS 


Finally, if only an error routine is specified, you would construct 
the argument list as follows: 


LIST: .WORD 2 ;NUMBER OF ARGUMENTS 
- WORD INRAB ;RECORD ACCESS BLOCK ADDRESS 
- WORD ERR1 ;ERROR ROUTINE ADDRESS 


Regardless of the macro format used to invoke an RMS-11l_ routine, 
RMS-11 preserves all general registers (RO-R5) across a macro call. 


9.1.3 Completion Routine Conventions 


The use of completion routines is always optional. If a corresponding 
address is present in the argument list, RMS-ll invokes an error or 
success completion routine based on the results of the operation 
attempted. When employing completion routines, you must be aware of 
conventions in the areas of: 


e Register usage 
@e Issuing RMS-11 macro calls within completion routines 
e Returning from a completion routine 


The subsections that follow discuss each convention. 


9.1.3.1 Register Usage Conventions Within Completion Routines - When 
RMS-1l calls a user-specified completion routine, the following 
register conventions are used: 


l. General register R5 contains the address of the same argument 
list, or a copy of the argument list, that was part of the 
calling sequence to RMS-1l itself. Therefore, you can use 
the control block address at 2(R5) to access fields of the 
control block. 


2. General registers RO-R4 are undefined. 


9.1.3.2 Issuing RMS-1l Macro Calls Within Completion Routines - As 
part of a completion routine, your program can issue an additional 
RMS~1l1 file or record processing macro call. RMS~-11 considers’ each 
such additional macro call as an extension of the original request 
that caused the completion routine to be _ invoked. The only 
restriction RMS-1l enforces is that a synchronous operation request 
cannot be issued within a completion routine called as a result of an 
asynchronous record operation. 
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9.1.3.3 Returning From a Completion Routine - To return control from 
a completion routine to RMS-ll, your program must: 


1. Restore the stack pointer SP to its original value at _ the 
time of entry to the completion routine. Your program must 
not attempt to cause control flow changes by modifying the 
stack. 


2. Issue a $RETURN macro. 

The format of the $RETURN macro is as follows: 
label: $RETURN 

where 


label is an optional user-defined macro referring to this 
SRETURN macro. 


9.1.4 Control Block Field Usage 


The fields within the control block associated with a particular macro 
call are the means by which you qualify or further define the 
requested file or record operation. For each particular operation, 
some number of control block fields will be used as input by RMS-1l. 
The tables that accompany each macro description in this’ chapter 
enumerate these fields. You must ensure, before your program issues a 
Macro call, that the appropriate fields in your control block contain 
the necessary values. 


You have three choices on how to set values in control block fields: 
1. Assembly-time initialization. 
2. Assembly-time defaulting. 
3. Runtime initialization. 


At assembly-time, you can explicitly initialize a field or, when a 
default is defined, allow the assembly-time expansion of the block 
allocation macros to set a default value in the field. At runtime, 
you can initialize or alter a control block field through use of the 
SSTORE, $SET, or SOFF macros. You must understand, however, that 
there are no runtime defaults for any field in any control block. If 
you fail to set (at assembly-time or runtime) every field in a control 

block that is defined as input to a particular operation, the 
~-operation may fail. . ee 


Consider the following example. You write a program that creates an 
indexed file and a sequential file. To save storage, you decide to 
allocate a single File Access Block. Therefore, your program will 
first create one file, close it, and then reuse the FAB to create the 
second file. You allocate a single key definition XAB (assuming your 
indexed file has only a single key). To create the indexed file 
first, you initialize all the appropriate fields of the FAB (e.g., ORG 
contains FBS$IDX, RFM contains, perhaps, FBSVAR, etc.). You place the 
address of the key definition XAB in the XAB field of the FAB. Then 
you define the primary key of the file through the fields of the XAB 
and you set the NXT (next XAB) field in the XAB to zero to indicate 
that there are no additional XABs. Finally, you issue the $CREATE 
Macro call and, if RMS-1ll indicates successful completion, you close 
the new file by issuing a $CLOSE macro call. 
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Now your program is ready to create the sequential file. Using the 
SSTORE macro, you alter the ORG field of the FAB so that it contains 
the value FBSSEQ. You further alter additional fields (RFM, FNA, FNS, 
MRS, etc.) so that they accurately describe your sequential file. 
However, you neglect to zero the XAB field in the FAB. When you issue 
the second SCREATE macro call, RMS-1l1 will find a valid address in the 
XAB field. It will then examine the XAB addressed by this field and 
find that it is a key definition XAB. Since sequential files do not 
have keys, RMS-11 will reject the create operation and return an error 
status code to your program. 


As the preceding example shows, you must appropriately set every field 
in a control block that RMS-1l1 may use during execution of an 
operation. RMS-1l assumes that every value found in an input field 
was intentionally placed there for use during the current operation. 
Since there are no runtime defaults for control block fields, you are 
responsible for the contents of all input fields prior to issuing a 
file or record operation macro call. 


9.1.5 Status Codes 


Before returning to your program from a file or record operation macro 
call, RMS-ll always indicates the success or failure of the requested 
operation by setting the STS field of the control block associated 
with the call. 


Through the use of the $COMPARE macro and the mnemonic’ status’ codes 
listed in Appendix A, your program can check for successful completion 
(SUSSUC) or particular error conditions. 


While particular error status codes are mentioned in certain sections, 
there is no attempt to list all possible error codes that can occur 
for every individual file or record operation. Such lists would tend 
to duplicate most of the list found in Appendix A. In writing 
programs, therefore, you must examine Appendix A and determine which 
error conditions you particularly want to test for following a macro 
call. For example, in reading a file, you always want to be prepared 
for the ERSEOF error status code (end of file). Whether you test for 
other error codes, such as ERSRLK (bucket is locked by another program 
or another stream in your own program) depends on the requirements and 
logic of your program. 


With certain error status codes, RMS-1l returns to your program 
additional information in the STV field of the control _ block 
associated with an operation. The descriptions of error status codes 
in Appendix A indicate those instances in which the STV field contains 
such information. 


9.2 PERFORMING FILE OPERATIONS 


A file operation macro call causes RMS-1l1 to perform some action 
related to an entire file. The macro call itself (e.g., SCREATE, 
SOPEN, $CLOSE) indicates the type of action desired. The fields of 
the File Access Block associated with the macro call identify the file 
or further qualify the requested action. 
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Table 9-1 summarizes the file operation macros provided by RMS-11: 


Table 9-1 
RMS-11 File Operation Macros 


Macro Name Description 


SCREATE 


Creates and opens a new RMS-1l1 file of any 
organization. 


SOPEN Opens an exiSting RMS-1l1 file making its 


contents available for processing. 


SDISPLAY Returns attributes of an RMS-1l file to the 


user program. 


SERASE Deletes an RMS-1l file and removes its entry 


from a directory. 


SEXTEND Extends the allocated space of an RMS-11l file. 


SCLOSE Closes an open RMS-1l1 file. 


The subsections that follow describe the action caused by each file 
operation macro and the control block fields that are input to and 
output from each operation. 


9.2.1 S$CREATE - Creating an RMS-11 File 


The $CREATE macro creates a new RMS-ll file with the attributes you 
specify in the File Access Block and any Extended Attribute Blocks 
chained to the FAB. When key definition or allocation XABs_ are 
present, they must be grouped in densely ascending order (i.e., 0, 1, 
2, 3, 4... in the REF or AID fields) without gaps or intervening XABs 
of other types. Otherwise, RMS-1l returns an ERSORD error code. An 
illogical XAB type in the chain (e.g-, a Summary XAB or a «key 
definition XAB for a sequential file) causes the ERSCOD error 
condition. If a NAM Block is also chained to the FAB, RMS-1l sets the 
ESL field of the block and places the expanded file specification in 
the area addressed by the ESA field of the NAM block. 


The SCREATE operation leaves the file open. Therefore, you must close 
the file by issuing a $CLOSE macro call. 


NOTE 


The S$CREATE operation requires 1 BDB and 
512 bytes of I/0 buffer space, all of 
which are released when the operation 
completes. You reserve space for BDBs 
through the use of the PS$BDB macro 
(refer to Chapter 3) and space for I/O 
buffers through the PSBUF macro (refer 
to Chapter 3) or the BPA and BPS fields 
of the FAB (refer to Chapter 5). The 
calculation of BDB and buffer space 
requirements is related to the 
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performance of record operations on the 
file. Since any record operations 
require at least 1 BDB and a buffer at 
least 1 virtual block in size, the BDB 
and buffer requirements for this file 
operation are typically met without 
specific attention on the part of the 
user. 


The formats of the SCREATE macro are as follows: 
1. label:SCREATE 


2. label: $CREATE fab[,error] 


where 
label is an optional user-defined symbol referring to the 
SCREATE macro. 
fab is the address of a File Access Block representing 
the file to be created. 
error is the address of a user completion routine to be 


called if the $CREATE operation fails. 
Table 9-2 lists the fields of the File Access Block used during the 
SCREATE macro call. 


Table 9-2 
SCREATE FAB Fields 


pene | esertpeton 


Allocation quantity (this field is ignored if one or 
more allocation XABs are present). 


Bucket size (this field is ignored for indexed files 
if one or more allocation XABs are present). 


Block size (magnetic tape files only). 

Buffer pool address. 

Buffer pool size. 

Default file extension quantity. 

Default name string address. 

Default name string size. 

File access (must contain at least the value FBSPUT). 
File name string address. 


File name string size. 


(Continued on next page) 
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Table 9-2 (Cont.) 
SCREATE FAB Fields 


pre] esertption 


Input file processing options. 
(Cont.) 
Fixed control area size (files with VFC format records 
only). 
Logical channel number. 
Maximum record number (relative files only). 
Maximum record size. 
Name block pointer. 
File organization. 
Record attributes. 


Record format. 


Retrieval window size. 


File sharing. 


Extended Attribute Block pointer. 
Output Device characteristics. 

Internal file identifier. 

Completion status code. 


Status value. 


9.2.2 S$OPEN - Opening an Existing File for Processing 


The SOPEN macro makes an existing file available for processing by 
your program. RMS-1l returns the basic attributes of the file in the 
fields of the File Access Block associated with the request. If 
Extended Attribute Blocks are chained to the FAB, RMS-11l fills in the 
attribute information represented by each XAB (e.g., key definition 
XAB, protection XAB, etc.). When either key definition or allocation 
XABS are present, they must be grouped in ascending order (by REF or 
AID, respectively) but need not be dense. No other intervening types 
are permitted. If this sequencing is violated, RMS-1ll returns an 
ERSORD error. Further, RMS-11l does not verify that the number of key 
definition or allocation XABs does not exceed the number of actual 
keys or areas defined for the file. Any such excess XABs are ignored. 
An illogical XAB type in the chain (e.g., key definition XAB for a 
sequential file) is similarly ignored. Additionally, if a NAM Block 
is chained to the FAB, RMS-1ll sets the ESL field in the NAM Block and 
places the expanded file specification of the open file in the 
location specified by the ESA field of the NAM Block. 
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NOTE 


The SOPEN operation requires 1 BDB_ and 
512 bytes of I/0 buffer space, all of 
which are released when the operation 
completes. You reserve space for BDBs 
through the use of the PSBDB macro 
(refer to Chapter 3) and space for I/O 
buffers through the PSBUF macro (refer 
to Chapter 3) or the BPA and BPS fields 
of the FAB (refer to Chapter 5). The 
calculation of BDB and buffer space 
requirements is related to the 
performance of record operations on the 
file. Since any record operations 
require at least 1 BDB and a buffer at 
least 1 virtual block in size, the BDB 
and buffer requirements for this file 
operation are typically met without 
specific attention on the part of the 
user. 


The formats of the SOPEN macro are: 
1. label:SOPEN 


2. label: SOPEN fab[,error] 


where 
label is an optional user-defined symbol referring to. the 
SOPEN macro. 
fab is the address of a File Access Block representing a 
file to. be opened. 
error is the address of a user completion routine to _ be 


called if the SOPEN operation fails. 
Table 9-3 lists the fields of the File Access Block used during’ the 
SOPEN macro call. 


Table 9-3 
SOPEN FAB Fields 


fname} tesertoetom | 


Buffer pool address. 


Buffer pool size. 


Default extend quantity. 
Default name string address. 
Default name string size. 


File access. 


(Continued on next page) 
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Table 9-3 (Cont.) 
SOPEN FAB Fields 


name] tesertptiom 


File name string address. 


Input 

(Cont.) 
File name string size. 
File processing options. 
Logical channel number. 
Name block pointer. 


Retrieval window size. 


File sharing. 


Extended Attribute Block Pointer. This field is 
optional. If present, RMS-1l will fill the indicated 
block (and any XABs chained to the first block) with 
the file attribute information indicated by the type 
of block present. 
Output Allocation quantity. Contains the highest numbered 
virtual block allocated to the file. 


Bucket size. Supplied for relative and indexed files 
and zeroed for sequential files. When multiple areas 
have been defined for an indexed file, BKS contains 
the size of the largest bucket in the file. 


Block size (sequential files on magnetic tape only). 


Device characteristics. 


file 


File processing options. Contains FBSCTG if the 


is contiguous. 


Fixed control area _ size. Supplied only if record 
format is VFC. 


Internal file identifier. 


Maximum record number. Supplied only if file 
organization is relative. 


Maximum record siees 
File organization. 
Record attributes. 
Record format. 
Completion status code. 


Status value. 
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9.2.3 $DISPLAY - Obtaining Attributes of a File 


The $DISPLAY macro retrieves file attribute information that you 
request and places the information in the fields of Extended Attribute 
Blocks. You must open the file in order to obtain attributes. 


RMS-1l1 determines the type of attribute information desired through 
examination of the types of Extended Attribute Blocks associated with 
the File Access Block by the XAB field. When either key definition or 
allocation XABs are present, they ‘must be grouped in ascending order 
(by REF or AID, respectively) but need not be dense. No other 
intervening types are permitted. If this sequencing is violated, 
RMS-11 returns an ERSORD error. Further, RMS-11 does not verify that 
the number of key definition or allocation XABs does not exceed the 
number of actual keys or areas defined for the file. Any such excess 
XABS are _ ignored. An illogical XAB type in the chain (e.g., key 
definition XABs for a sequential file) are similarly ignored. 


NOTE 


For the duration of its operation, 
SDISPLAY requires 1 BDB (refer to the 
P$BDB macro description in Chapter 3) 
and 512 bytes of I/O buffer space (refer 
to the PSBUF macro description in 
Chapter 3 or the BPS field description 
in Chapter 5). These requirements are 
in addition to the BDB and buffer space 
requirements for any streams that are 
connected at the time the S$DISPLAY call 
is issued. 


The formats of the S$DISPLAY macro are as follows: 
1. label: $DISPLAY 


2. label: $DISPLAY fab[,error] 


where 
label is an optional user-defined symbol referring to the 
SDISPLAY macro. 
fab is the address of a File Access Block representing a 
file whose attributes are to be returned to the user 
program. 
error is the address of a user completion routine to be 


called if the S$DISPLAY operation fails. 


Table 9-4 lists the fields of the File Access Block used during the 
SDISPLAY macro call. 
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Table 9-4 
SDISPLAY FAB Fields 


mame} eorsottom 


Input Extended Attribute Block pointer. 
Internal file identifier. 


Output Completion status code. 


Status value. Contains a system error code or the 
address of the XAB that caused an error. 


9.2.4 S$ERASE - Deleting a File 


The SERASE macro deletes an RMS-ll file and removes its directory 
entry. The space occupied by the file is’ returned at a system 
dependent time. You can issue a S$ERASE operation for a file currently 
accessed by another program or by your own program (so long as you are 
accessing it on a different logical channel). The file is not 
deleted, however, until all accessors close it. You cannot delete 
files on unit record or sequential (e.g., magnetic tape) devices. 


NOTE 


The SERASE operation requires 1 BDB' and 
512 bytes of I/0 buffer space, all of 
which are released when the operation 
completes. You reserve space for BDBs 
through the use of the PSBDB macro 
(refer to Chapter 3) and space for I/O 
buffers through the PSBUF macro (refer 
to Chapter 3) or the BPA and BPS fields 
of the FAB (refer to Chapter 5). The 
calculation of BDB and buffer’ space 
requirements is related to the 
performance of record operations on the 
file. Since any. record operations 
require at least 1 BDB and a buffer at 
least 1 virtual block in size, the BDB 
and buffer requirements’ for this file 
operation are typically met without 
specific attention on the part of the 
user. 


The formats of the SERASE macro are: 
1a label:SERASE 


2. label:SERASE fab[,error] 
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where 
label is an optional user-defined symbol referring to the 
SERASE macro. 
fab is the address of a file access block representing a 
file to be deleted. 
error is the address of a user completion routine to be 


called if the SERASE operation fails. 
Table 9-5 lists the fields of the File Access Block used during the 
SERASE macro call. 


Table 9-5 
SERASE FAB Fields 


Buffer pool address. 


Buffer pool size. 


Default name string address. 


Default name string size. 
File name string address. 
File name string size. 
Logical channel number. 
Output Completion status code. 


Status value. 


9.2.5 $EXTEND - Extending Allocated Space 


The SEXTEND macro extends the amount of space allocated to an RMS-1l 
file. The file must be open and any record access streams connected 
to the file must be inactive before the extension is attempted. 
Before you open the file, the FAC field in your FAB must specify at 
least one type of write operation (i.e., FBSPUT, FBSUPD, or FBSDEL). 
You cannot extend a file residing on magnetic tape. 


If no allocation XABs are present, RMS-1l extends, by default, area 0 
of the file or (for sequential or relative files) the file itself. 
The allocation quantity field (ALQ) of the File Access Block must 
contain the number of virtual blocks to be added to the file. In the 
FOP field of the FAB, you can request a contiguous extent (FBSCTG). 
If RMS-11 cannot allocate a contiguous extent, the SEXTEND operation 
will fail. 
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If you created an indexed file using allocation XABs (refer to Section 
7.6 in Chapter 7), you can selectively extend one or more areas of the 
file by providing appropriate allocation XABs as input to the SEXTEND 
operation. In this case, RMS-1l obtains the amount by which each area 
is to be extended from the ALQ field of each XAB. If you attempt to 
extend an area that has a currently unused extent, RMS-1l returns on 
ERSLEX error. Allocation XABs, when present, must be in ascending 
order by AID (area identification number) but need not be dense. 


The formats of the SEXTEND macro are: 
Li label:SEXTEND 


2. label:SEXTEND fab[,error] 


where 
label is an optional user-defined symbol referring to’ the 
SEXTEND macro. 
fab is the address of a file access block representing a 
file to be extended. 
error is the address of a user completion routine to be 


called if the $EXTEND operation fails. 
Table 9-6 lists the field of the File Access Block used during the 
SEXTEND macro call. 


Table 9-6 
SEXTEND FAB Fields 


pmeme] esertpttom 


ALQ | Allocation quantity. Ignored if one or more 
allocation XABs are present. 


File processing options. You can specify FBSCTG. 
This value will be ignored, however, if one or more 
allocation XABs are present. 
Internal file identifier. 


Extended Attribute Block Pointer (optional). 


Allocation quantity. This field will contain the 


actual number of virtual blocks added to the file. 


Output 


Completion status code. 


Status value. 
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9.2.6 S$CLOSE - Terminating File Processing 
The SCLOSE macro closes an open RMS-11 file. 


You should issue $DISCONNECT macro calls (refer to Section 9.3.1.2) 
for each record access stream associated with a file before issuing 
the SCLOSE macro. If you do not issue these $DISCONNECTs, RMS-11 will 
effectively disconnect all the file's record access streams. However, 
the SCLOSE operation will fail if there is an outstanding I/O request 
on any such stream. Further, the ISI (internal stream identifier) 
field in each RAB representing a stream will not be zeroed. Only the 
SDISCONNECT macro call zeroes this field. This action is desirable 
since it ends the association of a RAB with an internal RMS-11 
structure in the space pool. 


If RMS-ll returns a write error (ERSWER) in the STS field of the FAB, 
it has still closed and deaccessed the file. 


The formats of the SCLOSE macro are as follows: 


1. label:S$CLOSE 


2. label:$CLOSE fab[,error] 


where 
label is an optional user-defined symbol referring to’ the 
$CLOSE macro. 
fab is the address of a File Access Block representing the 
file to be closed. 
error is the address of a user completion routine to be 


called if the S$CLOSE operation fails. 
Table 9-7 lists the fields of the File Access Block used during the 
SCLOSE macro call. 


Table 9-7 
SCLOSE FAB Fields 


File processing options. You can specify FBS$RWC 
| (rewind tape volume on close). 


Internal file identifier. 


Output Internal file identifier. (Zeroed) 


Completion status code. 


Status value. 
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9.3 PERFORMING RECORD OPERATIONS 


After you open a file through a S$OPEN or S$CREATE macro call, you can 
perform record operations on the file. To perform such record 
operations, you must understand in detail the following: 


Record Access streams 

Record operations and file sharing 

Current context of record operations 

Synchronous and asynchronous record operations 

Accessing records 

The actual record operation macros (e.g., $GET, $PUT, SUPDATE, 
etc.) 


The following subsections describe each of these facilities. 


9.3.1 Record Access Streams 


To process records ina file, you must establish a record access 
stream. A record access stream is the logical association of a Record 
Access Block with a File Access Block. Once you have established a 
record access stream, you can issue operations on records in the file 
represented by the File Access Block. 


RMS-11 permits only one record access stream for sequential files. 
Thus, when you open or create a sequential file, you can associate 
only one RAB with the FAB representing the file. When you open or 
create a relative or indexed file, RMS-1l permits you to establish 
multiple record access streams by associating more than one RAB with 
the same FAB. 


When you establish a single record access stream for a file, your 
program uses the stream to issue a sequence of record operations. 
Within the stream, these record operations are executed serially. In 
other words, you can process’ only one record at a time. When you 
establish multiple record access streams for a file, your program can 
process more than one record of the file in parallel. Thus, such 
multiple streams represent independent ¥ and concurrently active 
sequences of record operations to the same file. 


After you open a file by issuing a SOPEN or a $CREATE macro call, you 
establish a record access stream by: 


1. Placing the address of the File Access Block in the FAB field 
of the appropriate Record Access Block. You can perform this 
action at runtime by using the $STORE macro or at 
assembly-time by using the RSFAB initialization macro. 


2. Issuing a $CONNECT macro. 


When you have completed the desired sequence of record operations, you 
terminate a record access stream by issuing a $DISCONNECT macro. 


The following subsections describe the $CONNECT and $DISCONNECT 
macros. 
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9.3.1.1 $CONNECT ~ Establishing a Record Access Stream - The $CONNECT 
Macro establishes a record access stream by associating a Record 
Access Block with a File Access Block. During the macro call, RMS-1ll 
allocates I/O buffers for the stream. These buffers are allocated 
from the file's private buffer pool (if such a pool was described by 
the BPA and BPS fields of the FAB during the S$OPEN or $CREATE 
operation) or from the centralized space pool. Additionally, RMS-11 
allocates, within the centralized space pool, internal control 
structures needed to support the stream. 


The formats of the SCONNECT macro are: 
1. label:S$CONNECT 


2. label:$CONNECT rab[,error[,success] ] 


where 

label is an optional user-defined symbol referring to the 
SCONNECT macro. 

rab is the address of a Record Access Block to_ be 
associated with a File Access Block. 

error is the address of a user completion routine to _ be 
called if the SCONNECT operation fails. 

success is the address of a user completion routine to _ be 


called if the SCONNECT operation succeeds. 
Table 9-8 lists the fields of the Record Access Block used during’ the 
SCONNECT operation. 


Table 9-8 
SCONNECT RAB Fields 


vane} etertpetom 


File access block address. 


Key of reference. Needed for indexed files only. 


Multi-block count (sequential disk files only). 
Multi-buffer count. 
Record processing options. 
User record area address (see RBF field below). 

Output Internal stream identifier. 
Record buffer address. Supplied only if locate mode 
for a sequential file was specified in the ROP field. 
RBF is set equal to UBF. 


Completion status code. 


Status value. 
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9.3.1.2 S$DISCONNECT - Terminating a Record Access Stream - The 
SDISCONNECT macro terminates a record access stream. The association 
of the specified Record Access Block to a File Access Block is’ ended. 
System buffers and internal control structures reserved for record 
processing by the stream are returned to the buffer pool. 


NOTE 


The S$DISCONNECT macro does not have’ the 
effect of an implicit SREWIND operation 
(refer to Section 9.3.6.6) for magnetic 
tape files. If you want to ensure that 
a magnetic tape file will be positioned 
to the beginning of file for a 
subsequent SCONNECT to the same open 
file, you must issue an explicit SREWIND 
operation before issuing the SDISCONNECT 
for the current stream. 


The formats of the SDISCONNECT macro are: 
1. label:SDISCONNECT 


2. label:$DISCONNECT rab[,error[,success] ] 


where 

label is an optional user-defined symbol referring to the 
SDISCONNECT macro. 

rab is the address of a Record Access’ Block whose 
association with a File Access Block is to be ended. 

error is the address of a user completion routine to be 
called if the SDISCONNECT operation fails. 

success is the address of a user completion routine to _ be 


called if the SDISCONNECT operation succeeds. 


Table 9-9 lists the fields of the Record Access Block used during the 
SDISCONNECT operation. 


Table 9-9 
SDISCONNECT RAB Fields 


sane] pescription 
ISI Internal stream identifier. 


Output ISI Internal stream identifier (zeroed). 


Completion status code. 


Status value. 


PERFORMING FILE AND RECORD OPERATIONS 


9.3.2 Record Operations and File Sharing 


RMS-11 allows your program to share access to a file with other 
concurrently executing programs. The manner in which a particular 
file can be shared is based on its organization. Whether a particular 
file is shared at runtime depends on information provided to RMS-1l by 
your program and other programs accessing the file. RMS-11 
coordinates record operations to a shared file through a bucket 
locking mechanism. The following subsections, therefore, describe: 


1. File organizations and file sharing. 
2. Program sharing information. 


3. Bucket locking. 


9.3.2.1 File Organizations and File Sharing - With the exception of 
files on unit record devices and magnetic tape, which cannot be 
shared, every RMS-11 file can be shared by any number of programs that 
are reading, but not writing, the file. Relative and indexed files 
(but not sequential files) can be shared by multiple readers and one 
Or more writers. Your program can read or write records in a relative 
or indexed file while other programs are similarly reading or writing 
records in the file. Thus, the information in such files can be 
changing while your program, or other programs, are accessing them. 


9.3.2.2 Program Sharing Information - While a file's organization 
establishes whether it can be shared by readers only or by multiple 
readers and writers, your program specifies whether such. sharing 
actually occurs at runtime. You control the sharing of a file through 
information your program provides RMS-11 in the File Access Block used 
to open the file. 


Two fields in the File Access Block provide RMS-1ll with file sharing 
information--the file sharing (SHR) field and the file access (FAC) 
field. The SHR field specifies what type of sharing you will allow. 
If the SHR field contains the value FBSWRI, you have indicated that 
you are willing to share the file with programs that are writing to 
the file. The absence of FBSWRI (i.e., SHR equals 0) indicates that 
you are willing to share the file with readers, but not writers. The 
FAC field declares the record operations that your program can itself 
perform on the file it is accessing. The presence of one or more of 
the values FBSPUT, FBSDEL, FBSUPD, or FBSTRN indicates that your 
program intends to write to the file. 


The contents of the SHR and FAC fields in the FAB you use to open a 
file are critical in the sharing of a file for the following reasons: 


1. If your program is the first to open a file, it can perform 
any record operation on the file as long as the organization 
of the file supports the operation and the operation is 
declared in your FAC field. However, the contents of your 
SHR field establish whether any other program desiring to 
write the file can also gain access. 
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2. If your program is not the first to access a file, RMS-1ll 
allows you. to open the file only if the contents of your FAC 
and SHR fields are compatible with the intentions of all 
programs that currently have access to the file. That is, 


a. If your FAC field indicates write operations and your SHR 
field indicates no one else can write, then: 


e All current accessors of the file must have 
specified FBSWRI in their SHR fields, and 

@e All current accessors must have indicated read only 
operations in their FAC fields. 


b. If your FAC field indicates read only operations and your 
SHR field indicates no one else can write, then: 


e All current accessors of the file must have 
indicated read only operations in their FAC fields. 


c. If your FAC field indicates read only operations and your 
SHR field allows writers, then: 


e There cannot be any current accessor who is writing 
and has disallowed writers. 


d. If your FAC field indicates write operations and your SHR 
field allows writers, then: 


e There cannot be any current accessor who has 
disallowed writers. 


9.3.2.3 Bucket Locking - RMS-11 uses a bucket locking facility to 
control operations to a relative or indexed file that is being 
accessed by one or more writers. The purpose of this facility is to 
ensure that a program can add, delete, or modify a record in a file 
without another program, or another record access stream within the 
Same program, Simultaneously accessing the same record. 


RMS-11 employs bucket locking in either of the following instances: 


1. The SHR field in the FAB of the first program to open a file 
specifies shared writing (i.e., FBSWRI). 


2. The SHR field in the FAB of the first program to open a file 
specifies shared reading only (i.e., SHR contains 0) but the 
FAC field in the same FAB declares one or more output 
operations (i.e., FBSPUT, FBSUPD, or FBS$DEL). 


In the first instance, RMS-1l1 locks any bucket accessed by a 
successful $GET or S$FIND operation issued from within any record 
access stream in any program processing the file. This lock prevents 
a second record access stream, in the same program or another program, 
from accessing any record in the same bucket. In the second instance, 
RMS-11 locks buckets accessed by $GET or S$FIND operation issued by the 
program whose FAC field indicates write operations. These locks, 
however, can be encountered only by other record access streams within 
the same program. 
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RMS-11 retains the lock on a bucket until the record access stream 
that caused the locking issues another record operation. While the 
lock is in effect, RMS-ll returns an ERSRLK (target bucket locked) 
error status code to other record access streams attempting to access 
the bucket. 


For greatest flexibility at runtime, you should always assume that any 
record your program attempts to access may be denied because of the 
target bucket locked (ERSRLK) condition. The bucket that you 
attempted to access can have been locked by another record access 
stream in your own program or a record access stream in another 
program. To deal with this condition, you should employ the following 
procedures when you write programs: 


1. Never allow a lock to be retained on a bucket longer than is 
necessary. That is, after you issue a successful $GET or 
SFIND operation, you have caused RMS-1l to lock a bucket. 
You should issue a second record operation in the same record 
access stream so that RMS-11 will unlock the _ bucket. Any 
record operation (e.g., $PUT, SUPDATE, SDELETE, or another 
$GET or $FIND) will cause unlocking. Alternatively, you can 
explicitly unlock the bucket by issuing the $FREE macro (see 
below). . | 


2. If you are using a single record access stream to access a 
file and you encounter the ERSRLK error, you can reissue the 
record operation that failed until RMS-11 indicates 
successful completion. 


3. If you are using multiple record access streams to access a 
file, you must not merely reissue the record operation that 
failed. Since one of your own record access streams may have 
caused locking of the target bucket, you could place your 
program in an infinite loop if you continue to issue the same 
operation. Therefore, you should issue a S$FREE (see below) 
for all other record access streams to the same file in your 
program. You can then safely reissue the original record 
operation until RMS-11 indicates successful completion. 


The SFREE macro unlocks a bucket that RMS-1l has locked on behalf of 
the record access stream. If no bucket is locked, RMS-1ll returns on 
ERSRNL (no bucket locked) error status code. 
The formats of the SFREE macro are as follows: 

1. label:$FREE 


2. label:SFREE rab[,error[,success]] 


where 

label is an optional user-defined symbol referring to’ the 
SFREE macro. 

rab is the address of a Record Access Block representing a 
record access stream. 

error is the address of a user completion routine to _ be 
called if the S$FREE operation fails. 

success is the address of a user completion routine to _ be 


called if the $FREE operation succeeds. 
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Table 9-10 lists the fields of the Record Access Block used during the 
SFREE operation. 


Table 9-10 
SFREE RAB Fields 


1 a 
Internal stream identifier 


Completion status code 


Status value 


9.3.3 Current Context of Record Operations 


Transparent to your program, RMS-1l maintains current context 
information for each record access Stream you establish. This context 
information identifies where, in a file, each record access stream is 
positioned at any point in time. As your program performs record 
operations on a record access stream, RMS-11l modifies, as necessary, 
the current context of that stream. 


At any point in time, the current context of a record access stream is 
represented by, at most, two records: 


1. The Current Record 
2. The Next Record 


The type of record operation you issue establishes whether or not, 
after the operation, there is a Current Record for the stream. 
Furthermore, the type of record operation and the access mode you use 
establish whether the identity of the Next Record is changed or 
unchanged. Table 9-11 summarizes the effect each successful record 
operation has on the current context of a stream. The subsections 
that follow describe the purpose and importance of the notions of 
Current and Next Records. 


Table 9-11 
Record Access Stream Context 
After Record Operations 


Current Identity of 
Record Operation Access Mode Record - Next Record 


SCONNECT First Record 
(for indexed files, 


established by index 
represented by KRF) 


SCONNECT End-of-file 
(ROP=RBSEOF ) (sequential files, 
: disk only) 


(Continued on next page) 
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Table 9-11 (Cont.) 
Record Access Stream Context 
After Record Operations 


Identity of 
Next Record 


Current 


Record Operation Access Mode Record 


SFIND Sequential ‘New Current Record +1 


SFIND Random or RFA Unchanged 
$GET 
(not immediately 


preceded by SFIND) 


Sequential New Current Record +1 


SGET Current Record +1 
(immediately 


preceded by S$FIND) 


Sequential Unchanged 


SGET Random or RFA 


New Current Record +l 


$PUT 1. Sequential file - 
EOF. 

2. Relative file - 
next relative 
record position. 

3. Indexed file 


undefined. 


Sequential 


$PUT Random Unchanged 


SUPDATE Unchanged 


$DELETE Unchanged 


$TRUNCATE 
SREWIND 
SFREE 
Unsuccessful 


record operations 
(except ERSRTB) 


NOTES 


for the 
establishes 
any) before 


l. Except 
RMS-11 
(if 


STRUNCATE 
the 
establishing 


identity of the Next Record. 


m4)" 
record 


2. The notation 
sequential 


organization of the file. 
current key of reference is 


files, the 


indicates 
as determined by the 


For 


part of this determination. 


the 


End-of-file 
First record 
Unchanged 


Unchanged 


operation, 
Current Record 


the 


next 


indexed 
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9.3.3.1 Understanding the Current Record - The Current Record 
associated with a record access stream represents the target record 
for an SUPDATE, $DELETE, or S$TRUNCATE operation. RMS-l1l rejects any 
SUPDATE, S$DELETE, or S$TRUNCATE operation you issue for a stream that 
does not have, at that point, a Current Record. 


To establish (or maintain) a Current Record for a stream, you must 
successfully issue one of the following: : 


1. A $FIND operation. 


2. A $GET operation (including $GET operations that return 
ERSRTB). 


As Table 9-11 shows, either of these two operations, if successful, 
establishes or retains a Current Record as part of the stream's 
context. Note that a successful, sequential S$GET operation that was 
immediately preceded by a successful S$FIND does not change the Current 
Record. Your program simply reads the record located by the preceding 
SFIND but that record continues to be the stream's Current Record. 
All other types of $GET operations and all $FIND operations’ establish 
new Current Records. 


In contrast to S$FIND and $GET operations, all other record operations, 
upon completion, leave the stream without a Current Record. Further, 
any unsuccessful record operation (excluding a S$GET that returns 
ERSRTB) leaves the stream without a Current Record. Therefore, any 
SUPDATE, SDELETE, or STRUNCATE operation your program issues must _ be 
immediately preceded by a successful $FIND or $GET operation. If you 
do not follow this procedure, RMS-1l rejects the SUPDATE, $DELETE, or 
STRUNCATE operation and returns the ERSCUR (No Current Record) error 
code. 


9.3.3.2 Understanding the Next Record - RMS-1ll utilizes the Next 
Record for sequential mode processing. A stream's Next Record 
represents the target record for: 


e A sequential SGET operation (if the immediately preceding 
operation was not $FIND) 


e A sequential $FIND operation 
e A sequential $PUT operation to a sequential or relative file 
For the preceding operations, RMS-1ll uses its internal knowledge of 
file organization and structure to determine the next record to be 
processed. This look ahead ability significantly decreases sequential 
mode access times. 
Initially, RMS-11l determines the Next Record as follows: 
The SCONNECT operation leaves the Next Record as: 
e The first record in a sequential disk file (unless the record 
processing options (ROP) field in the Record Access Block 
contains the value RBSEOF). 


e End of file in a magnetic tape file that has been opened for 
$PUT operations. 
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e The first record in a magnetic tape file if this is the first 
SCONNECT for a file opened for read only. Note that if there 
has been a previous SCONNECT followed by a SDISCONNECT for 
the open tape file, the SREWIND operation should be used to 
position the stream to beginning of file. 


e The first record in a relative file. 


e The first record in the collating sequence of the specified 
key of reference in an indexed file. 


Thereafter, RMS-1l1l alters the identity of Next Record as follows: 


e The SGET operation in any access mode, and the $PUT and SFIND 
operations in sequential mode leave the identity of the Next 
Record as that of the record following the one on which the 
operation was performed. This record is: 


1. The next record within sequential or relative files, or 


2. The next record as determined by the collating sequence 
of the specified key of reference in indexed files. 


e The STRUNCATE operation, which is allowed only on sequential 
files, sets the Next Record to point to the end of file. 
RMS-11 does not write EOF indicators in the file as a_ result 
of a STRUNCATE. 


The following operations have no effect on the Next Record: 
1. SUPDATE. 
2. $DELETE. 
3. $PUT or S$FIND in random access mode. 


4. All unsuccessful record operations (except ERSRTB). 


9.3.4 Synchronous and Asynchronous Record Operations 


Within each record access stream, your program can perform any record 
operation either synchronously or asynchronously. When a record 
operation is performed synchronously, RMS-1l returns control to your 
program only after the record operation request has been satisfied 
(e.g., a record has been read and passed to your program). When a 
record operation iS performed asynchronously, RMS-1l can return 
control to your program before the record operation request has been 
satisfied. Your program, then, can utilize the time required for the 
physical transfer between the file and memory of the block or bucket 
containing the record to perform other computations. 


To perform aSynchronous record operations, you must: 


1. Allocate, at assembly-time, an asynchronous Record Access 
Block to represent the stream in which you will issue 
asynchronous requests. You must allocate multiple 
asynchronous Record Access Blocks if you intend to issue 
asynchronous requests in parallel. (Refer to Section 6.1 in 
Chapter 6 for the details of allocating an asynchronous RAB.) 
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2. Ensure that the value RBSASY is present in the record 
processing options (ROP) field of the asynchronous RAB before 
you issue the desired record operation. You can initialize 
the ROP field at assembly-time with this value or set the 
field at runtime with the S$SET macro. Further, during 
execution, you can switch between synchronous and 
asynchronous operations in a stream by using the S$SET_ and 
SOFF macros to set and reset the value RBSASY in the ROP 
field. Note, however, that RMS-1l ignores the value RBSASY 
if the RAB is not asynchronous. 


When you issue an asynchronous record operation, you can specify a 
completion routine to be called if the operation succeeds. You can 
also specify an error completion routine to be called if the operation 
fails. Within such completion routines, you can issue additional 
operations. These additional operations, however, should also be 
asynchronous operations. If you issue a synchronous operation from an 
asynchronous completion routine, you may receive an ERSAST error if 
the completion routine was called at AST level in the task. 


While an asynchronous operation is in progress in a record access 
stream, you must: 


1. Never modify the contents of the Record Access Block 
representing the stream. 


2. Never issue a second record operation request in the same 
Stream until the first operation is completed. RMS-11 
returns an ERSRSA (record stream active) error status code if 
you issue a record operation to a stream which has a record 
operation in progress. 


To determine when an asynchronous record operation has completed, you 
issue the SWAIT macro. Upon completion of the asynchronous request 
for the associated RAB, RMS-1l returns control to your program at the 
point following the S$WAIT macro (after calling the appropriate 
completion routine, if specified). 


The formats of the SWAIT macro are as follows: 
1. label:SWAIT 


2. label: SWAIT rab 


where 
label is an optional user-defined symbol referring to the 
SWAIT macro. 
rab is the address of an asynchronous Record Access’ Block 


representing a record access stream with an 
asynchronous request in progress. 


Table 9-12 lists the fields of the Record Access Block used during the 
SWAIT operation. 


Table 9-12 
SWAIT RAB Fields 


[ame [eeription 

Internal stream identifier 

Output (dependent on operation waited upon) 
27 


Q- 
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9.3.5 Accessing Records 


To process a record in a file, you must specify an access mode in the 
Record Access Block representing a stream connected to the file. Your 
program can use one of two record transfer modes to access the subject 
record in memory after it has been read from the file or before your 
program writes it to the file. The following subsections, therefore, 
describe: 


e Specifying an access mode 


e Specifying a record transfer mode 


9.3.5.1 Specifying an Access Mode - You use the record access mode 
(RAC) field of the Record Access Block to specify the access mode that 
RMS~-11 is to employ for a particular record operation. During the 
execution of your program, you can Switch access modes within a stream 
by changing the contents of this field. 


Within the RAC field, you can specify one of three values: 


1. RBSSEQ  - sequential access mode. 
2. ™RBSKEY - random access mode. 
3. RBSRFA -—-_ record's file address access mode. 


You can specify sequential access mode with any file organization. 
Random accesS mode, however, is restricted to relative and indexed 
files. RFA access mode is limited to retrieval operations (i.e., 
S$GET, SFIND) to files residing on disk devices. 


RMS-11 examines the contents of the RAC field in a RAB only during the 
execution of a $GET, S$FIND, or $PUT operation. The $UPDATE, S$DELETE, 
and STRUNCATE operations do not require an access mode specification. 
You cannot issue these operations unless you have already accessed a 
record by issuing a S$GET or SFIND operation. 


9.3.5.2 Specifying a Record Transfer Mode - While the RAC field 
specifies how RMS-1l accesses a record in a file on behalf of your 
program, the record processing options (ROP) field in the RAB allows 
you to specify how your program (for $GET operations) or RMS-1ll (for 
$PUT or S$UPDATE operations) accesses the target record in memory. In 
the ROP field, you can specify one of two record transfer modes - move 
mode or locate mode. During execution of your program, you can switch 
record transfer modes within a stream by changing the contents of this 
field. 


Within the ROP field, you indicate: 
@ Move mode through the absence of the bit value RBS$LOC 
® Locate mode through the presence of the bit value RBS$LOC 


Move mode requires that RMS-11 move individual records between I/0 
buffers and the user program. For $GET operations, RMS-l1l1 reads a 
virtual block (Sequential files) or bucket (relative or indexed files) 
into an I/O buffer. RMS-11 then locates the desired record in the 
buffer and moves it to a program-specified location. For S$PUT or 
SUPDATE operations, your program first builds a record in any desired 
program location. Your program then stores the address and size of 
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the record in the RAB and issues the appropriate macro call. During 
execution of the macro call, RMS-1l moves the record from its 
specified location to an I/O buffer. When the buffer is filled, 
RMS-1ll writes it to the file. 


Locate mode enables your program to access records directly in an I/O 
buffer. Therefore, there is normally no _ need for RMS-1l1 to move 
records between I/O buffers and the user’ program. RMS-11 does not 
permit the use of locate mode if a file was opened for update 
operations (e.g., FAC contains the value FBSUPD). If a file has not 
been opened for update operations, then locate mode is supported for 
SGET operations for all file organizations. For S$PUT operations, 
locate mode is supported for sequentially organized files only. 


The record transfer mode you select for a particular record operation 
determines the use of the following fields of the RAB: 


Le Record address (RBF) and record size (RSZ). 


2. User record area address (UBF) and user record area size 
(USZ). 


The use of these fields is described in the following subsections. 


9.3.5.2.1 The RBF and RSZ Fields of the RAB - The RBF_ (record 
address) and RSZ (record size) fields of the RAB always describe the 
location in memory and the size of the target record for a $GET, $PUT, 
or $UPDATE operation. These fields are set as follows: 


l. For $PUT and SUPDATE operations, your program must always 
ensure that RBF and RSZ describe the location and size of the 
record to be written. 


2. After a successful $GET operation, RMS-11 always sets RBF to 
the address of the retrieved record and RSZ to the size of 
the record. 


Additionally, when your program is writing records to a _ sequential 
file in locate mode, RMS-1l1 returns an address in the RBF field after 
each S$PUT operation. This address is the location where your program 
can build the next record. It is not required that this location be 
used. If it is used, your program need only set the RSZ field to 
describe the size of the next record to be written. If it is not 
used, your program must, again, set both RBF and RSZ. 


9.3.5.2.2 The UBF and USZ Fields of the RAB - The UBF (user_ record 
area address) and USZ (user record area size) fields described a fixed 
work area in your program. Regardless of record transfer mode, you 
must alwayS provide this work area. Further, it should be large 
enough to contain the largest record in the file accessed by the 
stream. RMS-11 uses the work area described by UBF and USZ as 
follows: 


1. For $GET operations in move mode, RMS-1l moves the retrieved 
record from the 1/0 buffer to the location described by UBF. 
RBF (set equal to UBF) and RSZ describe the moved record. If 
the work area is not large enough to contain the entire 
record, RMS-1l moves as much of the record as possible (i.e., 
up to the amount specified in USZ), updates the current 
context of the stream, and returns the ERSRTB error code. 
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2. For $GET operations to any file in locate mode, RMS-11l will 
normally set RBF to the address of the record in an I/O 
buffer. However, if RMS-ll determines that locate mode 
cannot be used for a particular operation, RMS-11 will 
actually use move mode. That is, the record will be moved to 
the location described by UBF when move mode must be used, 
RMS-11 may return ERSRTB, as described above, if the user 
record area is too small. 


3. For S$UPDATE operations and S$PUT operations in move mode, 
RMS-11 ignores the UBF and USZ fields. You must describe the 
record to be written in the RBF and RSZ fields. 


4. For $PUT operations on sequential files in locate mode, 
RMS-11 uses the UBF and USZ fields as follows: 


e If the space remaining in the I/O buffer after the 
$PUT operation has been performed is equal to or 
greater than USZ, RMS-1l sets RBF to the _ location 
within the buffer where your program can build the 
next record. 


e If the space remaining in the I/O buffer is less than 
USZ, RMS-11 sets RBF equal to UBF. 


9.3.6 Record Operation Macros 
Table 9-13 summarizes the record processing macros provided by RMS-1l1: 


Table 9-13 
RMS-11 Record Processing Macros 


Macro Name Description 


SFIND Locates a record in a file and returns its RFA. 
$GET Retrieves a record from a file. 

$PUT Writes a new record into a file. 

SUPDATE Rewrites an existing record within a file. 


SDELETE Deletes a record from a relative or indexed file. 


SREWIND Positions to the beginning of a file. 


STRUNCATE Truncates a sequential file. 
SFLUSH Writes out modified I/O buffers. 


SNXTVOL Causes processing of a magnetic tape file to 
continue on the next volume of a volume set. 


The subsections that follow describe each of the record processing 
macros listed in the preceding table. Appendix A contains a complete 
list of completion status codes that can result from the issuance of 
these and other RMS-11 macros. 
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9.3.6.1 $FIND ~ Locating and Obtaining the RFA of a Record - The 
SFIND macro locates a specified record ina file and returns its 
record's file address into the RFA field of the RAB. Additionally, 
RMS-11 sets the record pointer and, for $FIND operations in sequential 
access mode, the next record pointer. The record pointer after a 
SFIND specifies which record will be the subject of the next 
sequential S$GET operation or a $DELETE, S$UPDATE, or STRUNCATE 
operation. 


The main uses of the S$FIND operation are as follows: 


1. Skipping records when in Sequential access mode (by issuing 
succesSive $FIND operations). 


2. Establishing a random starting point in a file for sequential 
access. 


3. Establishing a current record for a S$DELETE, S$UPDATE, or 
STRUNCATE operation. 


The formats of the S$FIND macro are as follows: 
1. label:SFIND 


2. label:$FIND rab[,error[,success] ] 


where 
label iS an optional user-defined symbol referring to the 
SFIND macro. 
rab is the address of a Record Access Block containing the 
specification of a record to be found. 
error is the address of a user completion routine to be 


called if the $FIND operation fails. 


success is the address of a user completion routine to be 
called if the SFIND operation succeeds. 


Table 9-14 lists the fields of the Record Access Block used during the 
SFIND operation. 


Table 9-14 
SFIND RAB Fields 


fone [baseeiption 


Internal stream identifier. 


Key buffer address. In combination with KSZ, KBF 
describes a record identifier for random access to 
a relative or indexed file. 


Key of reference. Used only for random access 
indexed files. 


Key size. 


Record access mode. 
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Table 9-14 (Cont.) 
SFIND RAB Fields 


jane [SC encription 


Input Record's file address. Used for RFA access only. 
(Cont.) 
Record processing options. 


Output Bucket code. When you access a relative file in 
sequential access mode, RMS-1l sets this field 


equal to the relative record number of the found 
record. 


Record's file address. 
Completion status code. 


Status value. 


The following subsections describe characteristics of the $FIND 
operation for the sequential, relative, and indexed file 
organizations. 


9.3.6.1.1 $FIND and the Sequential File Organization - Either 
sequential or RFA access mode can be used with the $FIND operation to 
a sequential file. RFA access, however, iS permitted only' for 
sequential files on disk devices. 


9.3.6.1.2 $FIND and the Relative File Organization - For the relative 
file organization, you can employ any of the three supported access 
modes with the S$FIND operation -- sequential, random, or RFA. 


When you specify sequential access mode, RMS-11 will locate the next 
existing record in the file. If no record exists in any remaining 
record positions, RMS-ll will return the ERSEOF error code (End of 
File) in the STS field of the RAB. 


Normally, you would not usSe RFA access mode with the $FIND macro since 
the output of the operation would be the identical record's file 
address used as input. However, a $FIND operation in RFA access’ mode 
could return a #ERSDEL (Record Deleted) error code. This error code 
indicates that the record described by the user-supplied record's file 
address once existed in the file but was subsequently deleted. 


Finally, random access mode can also be used for $FIND operations’ to 
relative files. Such an operation can result in an ERSRNF (Record Not 
Found) error if no record exists in the record position you specified 
through the KBF and KSZ fields of the RAB. 


9.3.6.1.3 $FIND and the Indexed File Organization - For the indexed 
file organization, you can use any of the three supported access 
modes -- sequential, random, and RFA. In random access mode, RMS-11 
uses the key of reference field (KRF) of the RAB to determine the 
index to be used to locate the record. 


PERFORMING FILE AND RECORD OPERATIONS 


In a $FIND operation in sequential access mode, RMS-11 will locate the 
next record in the sequence established by the index associated with a 
particular key of reference. RMS-11l uses the key of reference used by 
the most recent successful $GET or sequential $FIND operation or the 
key of reference contained in the KRF field at SCONNECT time. If a 
different index is desired for sequential processing, you should first 
issue a SREWIND operation specifying the new key of reference or issue 
a $GET in random access mode with the desired key of reference. 


SFIND operations in random access mode require the KRF field. You can 
specify any valid key of reference. If no record exists in the file 
that will satisfy the SFIND request, RMS-1l returns an ERSRNF (Record 
Not Found) error. 


During $FIND operations in RFA access mode, RMS-ll ignores the KRF 
field. The ERSDEL error code may be returned if the desired record 
once existed in the file but had been deleted subsequently. 


9.3.6.2 $GET - Retrieving a Record - The S$GET macro retrieves a 
record from any of the RMS-11l file organizations. The RBF and RSZ 
fields always describe the record retrieved after a _ successful 
operation. Further, RMS-1l sets the record pointer to the record's 
file address of the retrieved record and returns this value in the RFA 
field of the Record Access Block. These fields are valid only until 
the next operation on the RAB is issued. 


The formats of the SGET macro are as follows: 
1. label:$GET 


2. label:$GET rab[,error[,success] ] 


where 
label is an optional user-defined symbol referring to. the 
SGET macro. 
rab is the address of a Record Access Block containing the 
specification of the record to be accessed. 
error is the address of a user completion routine to be 


called if the S$GET operation fails. 


success is the address of a user completion routine to be 
called if the SGET operation succeeds. 


Table 9-15 lists the fields of the Record Access Block used during the 
SGET operation. 


Table 9-15 
SGET RAB Fields 


fee [enero 


Internal stream identifier. 


Key buffer. In combination with KSZ, KBF 
describes a record identifier for random access to 
a relative or indexed file. 
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Table 9-15 (Cont.) 
SGET RAB Fields 


mame | eserspttom 


Key of reference. Used only for’ random access’ to 
indexed files. 


Key size. 

Record access mode. 

Record's file address. Used for RFA access only. 
Record header buffer. Used for VFC format 


records. If this field equals 0, RMS-11 skips the 
fixed control area portion of the record. 


Record processing options. 


User record area address. 

User record area size. 

Bucket code. When you access a relative file in 
sequential access mode, .RMS-1l sets this field 
equal to the relative record number of the record 
retrieved. 


Record address. This field contains the address 
of the retrieved record. 


Record's file address. 


Record size. This field contains the size of 
record whose address is in RBF. 


Completion status code. 


Status value. See note below. 


NOTE 


After a successful S$GET operation from a 
unit record or terminal device, the low 
order byte of the STV field is used to 
report the terminating character for the 
input record. ‘This byte is set as 


follows: 
Octal Terminating 
Contents Character 
15 CR 
33 ESC 
32 CTRL/Z 
0 other 


Except when the low order byte of STV is 
0, the terminating character is never in 
the record described by the RBF and RSZ 
fields of the RAB. 
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The following subsections describe the characteristics of the S$GET 
operation for the sequential, relative, and indexed file 
organizations. 


9.3.6.2.1 $GET and the Sequential File Organization - Either 
sequential or RFA access mode can be used with the SGET operation to a 
sequential file. RFA access, however, iS permitted only for 
sequential files on disk devices. 


9.3.6.2.2 $GET and the Relative File Organization - For the relative 
file organization, you can employ any of the three supported access 
modes -- sequential, random, or RFA. 


When you specify sequential access mode, RMS-1l returns the next 
existing record in the file (or the Current Record if the immediately 
preceding operation was a successful S$FIND). If no record exists in 
any remaining record positions, RMS-1l returns the ERSEOF error code 
(End of File) in the STS field of the RAB. 


When you use random access mode, RMS-11 returns an ERSRNF (Record Not 
Found) error if no record exists in the record position you specified 
through the KBF and KSZ fields of the RAB. 


RMS-11 may return an ERSDEL (Record Deleted) error code for S$GET 
operations in RFA access mode. This error code indicates that the 
desired record once existed in the file but was subsequently deleted. 


9.3.6.2.3 $GET and the Indexed File Organization - For the indexed 
file organization, you can employ any of the three supported access 
modes -- sequential, random, and RFA. 


In a $GET operation (not preceded by a SFIND) in sequential access 
mode, RMS-11l retrieves the next record in the sequence established by 
the index associated with a particular key of reference. RMS-1ll uses 
the key of reference of the most recent successful $GET or SFIND 
operation or the key of reference contained in the KRF field at 
SCONNECT time. If a different index is desired for sequential 
processing, you should first issue a S$REWIND operation specifying the 
new key of reference or issue a $GET or $FIND in random access mode 
with the desired key of reference. 


S$GET operations in random access mode require the KRF field. You can 
specify any desired key of reference. If no record exists in the file 
that will satisfy the S$GET request, RMS-1l returns an ERSRNF (Record 
Not Found) error. 


During $GET operations in RFA access mode, RMS-1ll ignores the KRF 
field. The ERSDEL error code may be returned if the desired record 
has been deleted. 


9.3.6.3 $PUT - Writing a New Record to a File - The $PUT macro writes 
a new record into any RMS-1l1 file organization. The RBF and RS2Z 
fields must describe the record to be written. RFA access mode cannot 
be used. Note that S$PUT operations in random access mode do not 
change the next record pointer. 
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The following are the formats of the $PUT macro: 
1. label:$PUT 
2. label:S$PUT rab[,error[,success] ] 
where 


label is an optional user-defined symbol referring to the 
SPUT macro. 


rab is the address of a Record Access Block containing the 
specification of the record to be written. 


error is the address of a user completion routine to be 
called if the S$PUT operation fails. 


success is the address of a user completion routine to _ be 
called if the $PUT operation succeeds. 


Table 9-16 lists the fields of the Record Access Block used during the 
$PUT operation. 


Table 9-16 
SPUT RAB Fields 


preme | esertottom 


Internal stream identifier. 


Key buffer. Used only for random access’ to 
relative files. 


Key size. Used for random access to relative 
files only. 


Record access mode. 

Record address. 

Record header buffer. Used for VFC records only. 
If this field equals 0, RMS-1l zeroes the fixed 
control area portion of the record written. 

Record processing options. 

Record size. 

User record area. Used for locate mode _ for 
sequential files only (refer to Section 


9.3.5.2.2). 


User record area size. Used for locate mode _ for 
sequential files only. 


Bucket code. When you access a relative file in 
sequential access mode, RMS-ll sets this field 
equal to the relative record number of the’ record 
written. 


(Continued on next page) 


PERFORMING FILE AND RECORD OPERATIONS 


Table 9-16 (Cont.) 
SPUT RAB Fields 


dl a 


Record address. This field indicates where 
next record may be built. (locate mode on 
sequential files only) 


Record's file address. 


Completion status code. 


Status value. 


The following subsections describe the characteristics of the $PUT 
operation for the sequential, relative, and indexed file 
organizations. 


9.3.6.3.1 $PUT and the Sequential File Organization - You must ensure 
that the value RBSSEQ is preSent in the record access field (RAC) of 
the RAB at the time a $PUT macro call is issued for a sequential file. 
Further, RMS-11 does not permit new records to be added to a file at 
any place but the end of file. Therefore, if you intend to. add 
records to a sequential file that already contains records, either the 
value RBSEOF (position to end-of-file) must be present in the record 
options field (ROP) of the RAB at the time you issue the $CONNECT 
macro call for the stream or you must position to end-of-file through 
SFINDs and/or $GETs prior to issuing any $PUT requests. 


You cannot write any record whose length is greater than the maximum 
record size specified when the file was created. 


9.3.6.3.2 $PUT and the Relative File Organization - You can _ use 
either sequential or random access mode during $PUT operations to a 
relative file. For both access modes, three restrictions apply. 
First, no record can be written to the file whose length is greater 
than the maximum record size specified when the file was created. 
Second, the target record position cannot already contain a record. 
Third, the target record position cannot represent a relative offset 
from the beginning of the file whose value is greater than the maximum 
record number, if such a number was specified at the time the file was 
created. 


9.3.6.3.3 $PUT and the Indexed File Organization - You can use either 
sequential or random access mode during $PUT operations to an indexed 
file. For both access modes, two restrictions apply to the length of 
the record to be written. First, the length of the record cannot 
exceed the maximum record size specified when the file was created. 
Second, every record written must be large enough to contain a 
complete primary key field. It is not required, however, that records 
be large enough to contain all defined alternate key fields. If such 
alternate key fields are partially or completely missing because of 
record length, RMS-1l1 makes no entries for the new record in the 
associated alternate indexes. 
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$PUT operations to an indexed file do not require a key value or a key 
of reference. RMS-1l determines where to write the record by 
examining the contents of the primary key field in the record. Before 
writing the record, RMS-1l1 compares the key values (primary and 
alternate) in the record with the key values of records already 
existing in the file. This comparison determines if the writing of 
the record would result in the presence of duplicate key values among 
records of the file. If duplicates would occur, RMS-11l verifies the 
defined characteristics for the key field(s) being duplicated. If 
duplicates are not allowed for a particular key field, RMS-1l rejects 
the operation with an ERSDUP error code. However, if duplicates are 
allowed, RMS-11 performs the $PUT operation and returns a success code 
of SUSDUP. Subsequent sequential S$GET operations on a given index 
will always retrieve records with identical key values in the order in 
which the records were written. 


When you issue a series of $PUT operations in sequential access mode, 
RMS-11 checks that the primary key in each record is equal to (if 
duplicate primary key values are allowed) or greater than the primary 
key of the previous record written. An ERSSEQ (key out of sequence) 
error status code is returned if the primary key of the current record 
fails this’ check. This checking is suppressed, however, if the 
immediately preceding operation was not aé_e successful $PUT in 
sequential access mode. 


9.3.6.4 $UPDATE - Rewriting an Existing Record - The $UPDATE macro 
rewrites an existing record within a file. The Current Record 
associated with the stream will be rewritten. Therefore, the 
operation immediately preceding a SUPDATE must be a successful S$GET or 
SFIND. Otherwise, RMS-11 returns an ERSCUR (No Current Record) error 
code. The address and size of the replacement record must be in the 
RBF and RSZ fields respectively. Errors indicating an illegal input 
value in the RAB (e.g., ERSRSZ - illegal record size) do not effect 
the original record in the file. Other types of errors (e.g., 
ERSWER - file write error), however, can mean that the original record 
is lost. 


The following are the formats of the S$UPDATE macro: 
1. label: SUPDATE 
2. label:SUPDATE rab[,error[,success] ] 
where 


label is an optional user-defined symbol referring to the 
SUPDATE macro. 


rab is the address of a Record Access Block. 


error is the address of a user completion routine to _ be 
called if the SUPDATE operation fails. 


success is the address of a user completion routine to _ be 
called if the SUPDATE operation succeeds. 
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Table 9-17 lists the fields of the Record Access Block used during the 
SUPDATE operation. 


Table 9-17 
SUPDATE RAB Fields 


ane Description 


Internal stream identifier. 
Record address. 


Record header buffer. Used for VFC format records 
only. If no address is specified in this field, 
RMS-11 leaves the fixed control area portion of 
the original record unaltered. 


Record processing options. Note that locate mode 
is not supported for $UPDATE operations. 


Record size. 
Output Record's file address. 
Completion status code. 


Status value. 


The following subsections describe characteristics of the $UPDATE 
operation for the sequential, relative, and indexed file 
organizations. 


9.3.6.4.1  $UPDATE and the Sequential File Organization - RMS-1l does 
not permit the SUPDATE operation for sequential files residing on 
Magnetic tape or unit record devices. Furthermore, for disk files, 
the format of the records in the file cannot be stream and you cannot 
change the length of the record being rewritten. 


9.3.6.4.2 $UPDATE and the Relative File Organization - If the format 
of records is variable, the length of the replacement record can 
differ from the length of the original record. In all instances, 
however, you cannot issue a SUPDATE macro call specifying a 
replacement record whose length is greater than the maximum record 
size defined when the file was created. 


9.3.6.4.3 $UPDATE and the Indexed File Organization - On an $UPDATE 
operation to an indexed file that allows duplicate primary keys, you 
cannot change the length of the original record (RMS-11 returns ERSRSZ 
is you attempt such a change). For indexed files that do not allow 
duplicate primary keys, however, the length of the replacement record 
to be written by the $UPDATE macro call can differ from the length of 
the original record. Two restrictions, however, apply to the length 
of the replacement’ record. First, the length of the replacement 
record cannot exceed the maximum record size defined when the file was 
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created. Second, every replacement record must be large enough to 
contain a complete primary key field. It is not required, however, 
that the replacement record be large enough to contain all defined 
alternate key fields. If an alternate key field is partially or 
completely missing in the replacement record but was present in the 
Original record, the key field must have the characteristic that key 
values can change. This is also true if the replacement record 
contains a key field missing in the original record. 


Before writing the record, RMS-ll compares the key values of the 
Original record with the key values of the replacement record. This 
comparison takes into account the defined characteristics of each key. 
For example, if a particular key is not allowed to change, RMS-11 will 
reject the S$UPDATE operation with a ERSCHG error code if the 
replacement record contains an altered value in the associated key 
field. Similarly, if duplicates are not allowed for a particular key, 
RMS-1l rejects the operation with a ERS$DUP error code if writing the 
replacement record would cause duplicate values for the particular 
key. Conversely, if duplicates are allowed and writing the record 
results in the presence in the file of duplicate values for a 
Particular key, RMS-11 performs the write operation and returns a 
success code of SUSDUP. 


9.3.6.5 $DELETE - Deleting a Record - The $DELETE macro deletes an 
existing record from a relative or indexed file. This macro is an 
illegal operation for records in a sequential file. 
The S$DELETE operation always applies to the Current Record. 
Therefore, the operation immediately preceding a S$DELETE must be a 
successful SGET or SFIND. Otherwise, RMS-1l returns an ERS$CUR_ (No 
Current Record) error code. 
The formats of the $DELETE macro are as follows: 

1. label: SDELETE 

2. label: S$SDELETE rab[,error[,success] } 


where 


label is an optional user-defined symbol referring to the 
SDELETE macro. 


rab is the address of a Record Access Block. 


error is the address of a user completion routine to be 
called if the SDELETE operation fails. 


success is the address of a user completion routine to be 
called if the $DELETE operation succeeds. 


Table 9-18 lists the fields of the Record Access Block used during the 
SDELETE operation. 
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Table 9-18 
SDELETE RAB Fields 


p= [en 


Internal stream identifier. 


Record processing options. 


Completion status code. 


Status value. 


9.3.6.6 $REWIND - Positioning to the Beginning of a File - The 
SREWIND macro sets the current context of a stream to the beginning of 
a file. Following the operation, there is no Current’ Record. The 
Next Record is the first record in the file (for indexed files, the 
KRF field establishes the index to be used). 
The following are the formats of the S$REWIND macro: 

l. label: S$REWIND 

2. label:SREWIND rab[,error[,success] ] 
where 


label is an optional user-defined symbol referring to the 
SREWIND macro. 


rab is the address of a Record Access Block associated with 
a file. 
error is the address of a user completion routine to _ be 


called if the SREWIND operation fails. 


success is the address of a user completion routine to _ be 
called if the SREWIND operation succeeds. 


Table 9-19 lists the fields of the Record Access Block used during the 
SREWIND operation. 


Table 9-19 : 
SREWIND RAB Fields 


pone | eseesotton 


Internal stream identifier. 


Key of reference. Used for indexed files only. 


Completion status code. 


Status value. 
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9.3.6.7 STRUNCATE - Truncating a Sequential File - The STRUNCATE 
Macro truncates a sequential file. This operation is illegal for 
relative and indexed files. 


STRUNCATE deletes the Current Record and all records following that 
record. The immediately preceding operation must be a successful $GET 
or $FIND. Otherwise, RMS-1l returns an ERSCUR (No Current Record) 
error code. 
RMS-11 declares an end-of-file at the position formerly occupied by 
the Current Record. Additionally, the STRUNCATE operation causes the 
Next Record to point to this end-of-file. Therefore, you can extend 
the file by issuing $PUT operations in sequential mode following the 
STRUNCATE operation. 
The following are the formats of the STRUNCATE macro: 

l. label: $TRUNCATE 

2. label: STRUNCATE rab[,error[,success] ] 
where 


‘label is an optional user-defined symbol referring to the 
STRUNCATE macro. 


rab is the address of a Record Access Block associated with 
a sequential file. 


error is the address of a user completion routine to be 
called if the STRUNCATE operation fails. 


success is the address of a user completion routine to be 
called if the STRUNCATE operation succeeds. 


Table 9-20 lists the fields of the Record Access Block used during the 
STRUNCATE operation. 


Table 9-20 
STRUNCATE RAB Fields 


2 
Internal stream identifier. 


Completion status code. 


Status value. 


9.3.6.8 $FLUSH - Writing Out Modified I/O Buffers - The $FLUSH macro 
writes out all modified I/O buffers associated with a record access 
stream, thus ensuring that all record activity up to a point in time 
is actually reflected in the file. If the file is relative or 
indexed, any bucket currently locked by the stream remains locked. 
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The formats of the $FLUSH macro are as follows: 
1. label:$FLUSH 
2. label:SFLUSH rab[,error[,success] ] 
where 


label is an optional uSer-defined symbol referring to the 
SFLUSH macro. 


rab is the address of a Record Access Block representing a 
stream to be flushed. 


error is the address of a user completion routine to be 
called if the $FLUSH operation fails. 


success is the address of a user completion routine to be 
called if the $FLUSH operation succeeds. 


Table 9-21 lists the fields of the Record Access Block used during the 
SFLUSH operation. 


Table 9-21 
SFLUSH RAB Fields 


| escrsption | 
Internal stream identifier. 


Completion status code. 


Output! STS 
STV 


9.3.6.9 $NXTVOL - Continue Processing on Next Volume - The SNXTVOL 
macro can be used only when the stream is accessing a file on magnetic 
tape. You issue this macro when you want to continue processing the 
file on the next volume of a volume set before the end of the current 
volume is reached. RMS-11l will then open the first file section on 
the next volume. File sections occur when a file is written on more 
than one volume. The portion of the file on each of the volumes 
constitutes a file section. For input files, the following processing 
occurs when you issue a S$NXTVOL macro: 


Status value. 


1. All records in I/O buffers for the current file section are 
skipped. 


2. If the current volume is the last volume in the set, i.e., 
there is no next volume, RMS-11 reports end-of-file to your 
program. 


3. If another file section exists, the current volume iS rewound 
and the next volume iS mounted. A request to the operator is 
printed if necessary. 


4. The header label (HDR1) of the first file section is read and 
checked. 
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5. If all required fields check, the operation continues. 


6. If any check fails, the operator is requested to mount the 
correct volume. 


For output files, the following processing occurs. 


1. I/O buffers that are currently in memory are written on _ the 
current file section (i.e., an implicit S$FLUSH is performed). 


2. The current file section is closed with EOV1 and EOV2 labels 
and the volume is rewound. 


3. The next volume is mounted. 

4. A file with the same name and the next higher section number 
is opened for write. The file set identifier is identical 
with the volume identifier of the first volume in the volume 
set. 

The formats of the SNXTVOL macro are as follows: 

1. label: SNXTVOL 


2. label: $NXTVOL rab[,error[,success] ] 


where 
label is an optional user-defined symbol referring to the 
SNXTVOL macro. 
rab is the address of a Record Access Block associated with 
a file on a magnetic tape volume set. 
error is the address of a user completion routine to be 


called if the SNXTVOL operation fails. 


success is the address of a user completion routine to be 
called if the SNXTVOL operation succeeds. 


Table 9-22 lists the fields of the Record Access Block used during the 
SNXTVOL operation. 


Table 9-22 
SNXTVOL RAB Fields 


fname | eseription 
malt 


Internal stream identifier. 
Output STS 
STV 


Record processing options. 


Completion status code. 


Status value. 
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COMPLETION STATUS CODES 


This appendix describes completion status codes that can be returned 
by RMS-11 to your program. 


All RMS-11 file and record operations return a completion status code 
into the status field (STS) of the control block (i.e., FAB or RAB) 
associated with the operation. A symbolic name is defined for’ each 
such code. The symbolic names for successful completion status codes 
take the following form: 


SUSxxx 
where 


XXX is a mnemonic value describing the’ successful 
operation. 


Symbolic names for error completion status codes take the form: 
ERSxxx 


where 


XXX is a mnemonic value representing the reason’ the 
operation failed. 


For certain error conditions, RMS-1l uses the status value (STV) field 
to communicate additional information to your program. The tables in 
this appendix list all instances in which a particular symbolic value 
in the STS field indicates the presence of further information in the 
STV field. 


NOTE 


When the tables in this appendix 
indicate that the STV field contains an 
ACP error code, you should refer to’ the 
description of such codes in Appendix I 
of the IAS/RSX-11 I/O Operations 
Reference Manual. 


A limited number of severe error conditions cause RMS-1l to invoke a 
fatal error crash routine. Section A.3 of this appendix describes 
these conditions and the crash routine itself. 


The sections that follow describe, respectively, successful completion 
Status codes, error completion status codes, and the RMS-11 fatal 
error crash routine. 
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A.1 SUCCESSFUL COMPLETION STATUS CODES 
Table A-l describes successful completion status codes returned by 
RMS-11 routines. 


Table A-1 
Successful Completion Status Codes 


Symbolic Decimal Description 
Name Value 


SUSSUC Operation successful. 


SUSDUP A record written into an indexed file as a 
result of a $PUT or SUPDATE operation contains 
at least one key value that was already present 
in another record. 


SUSIDX During a $PUT or SUPDATE operation on an 
indexed file, the record was’ successfully 
written. The record can be subsequently 
retrieved but RMS-1l was not able to optimize 
the structure of the index at the time the 
record was inserted. Several indirections will 
occur, therefore, on retrieval. In some 
instances, RMS-1l may also return an error code 
(e.g., ERSRLK) in the STV field of the control 
block. 


SUSRRV During a $PUT or S$UPDATE operation on an 
indexed file, the record was’ successfully 
written. However, RMS-1l was unable to update 
one or more Record Retrieval Vectors (RRVs) and 
the records associated with the RRVs cannot be 
retrieved using alternate indexes or RFA 
addressing mode. 


A.2 ERROR COMPLETION STATUS CODES 


Table A-2 describes error completion status codes returned by RMS-1l 
routines. 


Table A-2 
Error Completion Status Codes 


Symbolic Octal |Decimal Description 
Value Value Value 


ERSABO 177760 ERSSTK Operation aborted: out of 
or Stack Save area or in core 
ERSMAP data structures corrupted. 


ERSACC 177740 ACP error Files-ll ACP could not access 
code the file. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV Description 
Value Value Value 
48 


ERSACT 


File activity precludes 
action (e.g., attempting to 
close a file with outstanding 
asynchronous record 
operation). 


ERSAID XAB address Bad area identification 
number (AID) field in 
allocation XAB (i.e., out of 
sequence). 


ERSALN 177660 XAB address Illegal value in alignment 
boundary type (ALN) field of 
allocation XAB. 


ERSALQ 177640 (XAB address) | Value in allocation quantity 
(ALQ) field in FAB (or 
allocation XAB ) exceeds 
maximum Or, during an 
explicit SEXTEND operation, 
equals zero. 


ERSANI 177620 Records in a file on ANSI 
labeled Magnetic tape are 
variable length but not in 
ANSI D format. 


ERSAOP 177600 XAB address Illegal value in allocation 
options (AOP) field in 


allocation XAB. 


ERSAST Invalid operation at AST 
level: attempting to issue a 
synchronous operation from an 
asynchronous record operation 
completion routine. 


ERSATR 177540 ACP error Read error on file header 
code attributes. 


ERSATW 177520 ACP error Write error on file header 
code attributes. 


ERS$BKS 177500 Bucket size (BKS) field in 
FAB contains value exceeding 
maximum. 


ERSBKZ 177460 XAB address Bucket size (BKZ) field in 
allocation XAB contains value 
exceeding maximum. 


ERSBLN 177440 Block length (BLN) field ina 
FAB or RAB is incorrect. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV 
Value Value Value 


Description 


ERSBOF 


ERSBPA 


ERSBPS 


ERSBUG 


ERSCCR 


ERSCHG 


ERSCHK 


ERSCLS 


ERSCOD 


ERSCRE 


ERSCUR 


ERS DAC 


ERS DAN 


ERS DEL 


177220 


177200 


177160 


177140 


177120 


RSTS/E 
error code 


XAB address 


ACP error 
code 


ACP error 
code 


XAB address 


Beginning of file detected on 
SSPACE operation to magnetic 
tape file. 


Private buffer pool address 
not a double word boundary. 


Private buffer pool size not 
a multiple of 4. 


Internal error detected in 
RMS-11 (refer to Section A.3 
of this Appendix); no 
recovery possible; contact a 
Software Specialist. 


Can't connect RAB (i.e., only 
one record access stream 
permitted for sequential 
files). 


SUPDATE attempting to change 
a key field that does not 
have the change attribute. 


Index file bucket check-byte 
mismatch. The bucket has 
been corrupted. No recovery 
possible for the bucket. 


Close function failed (RSTS/E 
operating system only). 


Invalid COD field in XAB_ or 
XAB type is illegal for the 
organization or operation. 


Files-ll ACP could not create 
file. 


No current record: operation 
not immediately preceded by a 
successful S$GET or $FIND. 


Files-ll ACP deaccess error 
during SCLOSE 


Invalid area number in .DAN 
field of key definition XAB. 


Record accessed by RFA access 
mode has been deleted. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Octal |Decimal Description 
Value Value 


177100 1. Syntax error in device 
name. 

2. No such device. 

3. Inappropriate device for 
operation (e.g., 
attempting to create an 

indexed file on magnetic 

tape). 


Symbolic 
Value 


ERS DEV 


ERSDIR 177060 Syntax error in directory 


name. 


ERS DME 177040 Dynamic memory exhausted: 
insufficient space in 
central space pool or 


private buffer pool. 


ERS DNF 


177020 Directory not found. 


177000 


ERSDNR Device not ready. 


ERSDPE 176770 


ACP error 
code 


Device positioning error. 


ERSDUP 176740 


Duplicate key detected, 
duplicates allowed 
attribute not set for one 
Or more key fields. 


ERSENT 176720 


Files-ll ACP 
failed. 


ACP error enter function 


code 


ERSENV 176700 Environment error: operation 
or file organization not 


specified in ORG$ macro. 


ERSEOF 176660 End of file. 


ERSESS 176640 


Expanded string area in NAM 
block too short. 


ERSEXP 176630 File expiration date not 


reached. 


ERSEXT 176620 


ACP error File extend failure. 


code 


ERSFAB 176600 Not a valid FAB: BID field 
does not contain FBSBID. 
Refer to Section A.3 of 


this Appendix. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV Description 


Value 


ERSFAC 


ERSFEX 


ERSFID 


ERSFLG 


ERSFLK 


ERSFND 


ERSFNF 
ERSFNM 
ERSFOP 


ERSFUL 


ERSIAN 


ERS IDX 


ERSIFI 


ERSIMX 


ERSINI 


Value 


176560 


176540 


177530 
176520 


176500 


176460 


176440 
176420 
176400 


176360 


176340 


176320 


176300 


176260 


176240] 


Value 


XAB address 


ACP error 
code 


XAB address 


XAB address 


1. Record operation attempted 
was not declared in FAC 
field of FAB at open time. 

2. Invalid contents in FAC 
field. 

3. FBSPUT not present in FAC 
for $CREATE operation. 


exists 
SCREATE 


File 
(attempted 
operation). 


already 


Invalid file id. 


Invalid combination of values 
in FLG field of key 
definition XAB (e.g, no 
duplicates and keys can 
change). 


File locked by another’ user 
-- you cannot access the file 
because your sharing 
specification cannot be met. 

ACP Find 


Files-ll function 


failed. 

File not found. 

Syntax error in file name. 
Invalid file options. 

can't create or 


Device full: 
extend file. 


Invalid area number in IAN 
field of key definition XAB. 


Index not initialized (this 
code can only occur in the 
STV field when STS_ contains 
ERSRNF). 


Invalid IFI field in FAB. 


Maximum number (254) of key 
definition or allocation XABs 
exceeded or multiple summary, 
protection, or date XABs 
present during operation. 
SINIT or SINITIF macro call 
never issued. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV Description 
Value Value Value 


ERS IOP Illegal operation; examples 
include: 
Attempting a S$TRUNCATE 
operation to a 
non-sequential file. 
Attempting an $ERASE or 
SEXTEND operation to a 
Magnetic tape file. 


Issuing a block mode 
Operation (e.g., SREAD 
or S$WRITE) to a stream 
not connected for block 
operations. 

Issuing a record 
Operation (e.g., S$GET, 
SPUT) to a stream 
connected for block 
mode operations. 


ERS IRC Illegal record encountered in 
sequential file: invalid 
count field. 


ERSISI Invalid internal stream 
identifier (ISI) field in RAB 
(field may have been altered 
by user) or $CONNECT never 
issued for stream. 


ERSKBF Key buffer address (KBF ) 
field equals 0. 


ERSKEY Record identifier (i.e., the 
4-byte location addressed by 
KBF) for random operation to 
relative file is 0 or 
negative. 


ERSKRF Invalid key of reference 
(KRF) in RAB: 1) As input to 
random SGET Or SFIND 
operation, or 2) As input to 
SCONNECT or S$REWIND (in this 
case, ERSKRF is returned for 
the first record operation 
following the $CONNECT or 
SREWIND. 


ERSKSZ Key size equals zero or _ too 
large (indexed file) or not 
equal to 4 (relative file). 


XAB address Invalid area number in LAN 
field of key definition XAB. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic | Octal |Decimal] STV . Description 
Value Value Value 


ERSLBL Magnetic tape is not ANSI 
labeled. 


ERSLBY Logical channel busy. 


ERS$LCH Invalid value in logical 
channel number (LCH) field of 
FAB. 


ERS LEX XAB address Attempt to extend an area 
containing an unused extent. 


ERS LOC XAB address Invalid value in LOC field of 
allocation XAB. 


ERSMAP In core data structures 
(e.g., I/O buffers) 
corrupted. This code can 
only occur in the STV field 
when STS contains ERSABO 
Refer also to Section A.3 of 
this Appendix. 


ERSMKD ACP error Files-1l ACP could not mark 
code file for deletion. 


ERSMRN 1. Maximum record number 
field contains a negative 
value during SCREATE of 
relative file. 

2. Record identifier (pointed 
to by KBF) for random 
operation to relative file 
exceeds maximum record 
number specified when file 
created. 


ERSMRS 175640 Maximum record size (MRS ) 
field contains 0 during 
SCREATE operation and: 
1. Record Format is fixed, 
or 
2. File organization is 
relative. 


ERSNAM 175620 Odd address in Name Block 
address (NAM) field in FAB on 
SOPEN, SCREATE, or SERASE. 


ERS NEF 175600 Not at end-of-file: 
attempting a S$PUT operation 
to a sequential file when 
Stream is not positioned to 
EOF. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV Description 
Value Value Value 


175560 


ERSNID Can't allocate internal index 
descriptor: insufficient 
room in space _ pool while 
attempting to open an indexed 


file. 


175540 


ERSNPK No primary key definition XAB 
present during SCREATE of 


indexed file. 


ERSOPN 175520) -1200 | RSTS/E 


error code 


Open function failed (RSTS/E 
operating system only). 


ERSORD 175500} ~1216 | XAB address XABs in chain not in correct 
order: 

1. Allocation or key 
definition XABs not in 
ascending (or densely 
ascending) order. 


2. XAB of another type 


intervenes in key 
definition Or 
allocation XAB 


sub-chain. 


ERSORG 175460 Invalid value in file 


Organization (ORG) field of 
FAB. 


ERS$PLG 175440 Error in file's prologue: 
file is corrupted and must be 


reconstructed. 


ERS$ POS 


175420 XAB address Key position (POS) field in 
key definition XAB contains a 
value exceeding maximum 


record size. 


ERS PRM 


175400 


XAB address File header contains bad date 
and time information 
(retrieved by RMS-1ll because 
a date and time XAB_ is 
present during a SOPEN or 
SDISPLAY operation) ; file 
may be corrupted. - 


ERS PRV Privilege violation: access 
to the file denied by the 


operating system. 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV Description 
Value Value Value 


Not a valid RAB: BID field 
does not contain RBSBID. 
Refer to Section A.3 of this 
Appendix. 


Illegal values’ in record 
access mode (RAC) field of 
RAB. 

Illogicai value in RAC 
field (e.g., RBSKEY with a 
sequential file). 


Illegal values’ in record 
attributes (RAT) field of 
FAB during S$CREATE. 
Illogical combination of 
attributes (e.g., FBSCR 
and FBSFTN) in RAC. field 
during $CREATE. 


ERSRBF Record address (RBF) field in 
RAB contains an odd address 
(block mode access only). 


ERSRER ACP error File read error. 
code 


ERSREX Record already exists: 
during a S$PUT operation in 
random mode to ae relative 
file, an existing record 
found in the target’ record 
position. 


ERSRFA Invalid RFA in RFA field of 
RAB during RFA access. 


ERSRFM 1. Invalid record format in 
RFM field of FAB during 
SCREATE. 
2. Specified record format is 
illegal for file 
organization. 


ERSRLK Target bucket locked by 
another task Or another 
stream in the same program. 


ERSRMV -1456 |ACP error -| Files-11 ACP Remove’ function 
failed. 


(Continued on next page) 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV Description 
Value Value Value 


ERSRNF 175100 (ERSIDX) Record identified by KBF/KSZ 
fields of RAB for random SGET 
or $FIND operation does not 
exist in relative or indexed 
file (for indexed files only, 
STV may contain ERSIDX). 
Record may never have been 
written or may have been 
deleted. 


ERSRNL SFREE operation issued but no 
bucket was locked by stream. 


ERSROP Record options (ROP) field 
contains illegal values or 
illogical combination of 
values. 


ERSRPL 175020 ACP error Error while reading prologue. 
code 


ERSRRV 175000 Invalid RRV record 
encountered in indexed file; 
file may be corrupted. 


ERSRSA 174760 Record stream active, i.e., 
in asynchronous environment, 
attempting to issue a_ record 
operation to a stream that 
has a request outstanding. 


ERSRSZ 174740 Record size specified in RSZ 
of RAB during $PUT or SUPDATE 
is invalid: 

1. RSZ equals zero. 

RSZ exceeds maximum record 
size (MRS) specified when 
file created. 

RSZ not equal to size of 
Current Record for $UPDATE 
operation to a sequential 
file on disk. 

RSZ does not equal MRS 
(for fixed format 
records). 


ERSRTB -1584 |Actual record} Record too big for user's 
buffer: RMS-11 could not 
move entire record retrieved 
by $GET operation to user 
work area (UBF/USZ). Note 
that this error does not 
destroy the current context 
of the stream. Rather, the 
stream's context is updated 
as if the operation had been 
completely successful. 


(Continued on next page) 
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Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic Octal |Decimal STV Description 
Value Value Value 


ERSSEQ 174700; -1600 During $PUT operation, key of 
record to be written is not 
equal to or greater than key 
of previous record (and RAC 
field contains RBSSEQ). 


174660 


ERSSHR Illogical value in SHR field 


of FAB (e.g., FBSWRI 
specified for sequential 
file). 


174640 XAB address 


ERSSIZ Invalid SIZ field in key 
definition XAB during SCREATE 
(e.g.-, Specified size exceeds 


maximum record size). 


ERSSTK 174620 During asynchronous record 
operation, RMS-1ll has found 
that the stack is too big to 
be saved (this code can only 
occur in the STV field when 


STS contains ERSABO). 


ERSSYS 174600 Directive or 
QIO status 


code 


System directive error. 


174560 


Index tree error: indexed 
file is corrupted. 


ERSTRE 


ERSTYP 174540 Syntax error in file type 
(e.g-, more than 3 characters 
specified). 
ERSUBF Invalid address in UBF field 
of RAB: . 

1. UBF contains 0, or 

2. UBF not word aligned (for 


block mode access only). 


174500 Invalid USZ field in RAB 


(i-e., USZ contains 0). 


ERSUSZ 


ERSVER 


174460 Syntax error in file version 


number. 


174440 Invalid VOL field in 
allocation XAB (i.e., VOL 


does not contain 0). 


ERSVOL XAB address 


174420 


File write error. 


ERSWER -1776 {ACP error 


(Continued on next page) 


A-12 


COMPLETION STATUS CODES 


Table A-2 (Cont.) 
Error Completion Status Codes 


Symbolic | Octal {Decimal STV Description 
Value Value Value 


174410 


ERSWLK -1784 Device is write locked. 


ERSWPL 174400] -1792 


ACP error 
code 


Error while writing prologue. 


- ERSXAB 174360| -1808 | (XAB address) | XAB field in FAB (or NXT 


field in XAB) contains an odd 
address. 


A.3 FATAL ERROR CRASH ROUTINE 


RMS-11 issues a BPT instruction whenever it encounters’ inconsistent 
internal f FAB or RAB). This action is taken only when RMS-11l cannot 
continue processing, since to do so might cause damage to user files 
or the user's task image. As an example, when the problem is caused 
by an invalid FAB or RAB, RMS-1l cannot return an error status code in 
STS since it has no recognizable user control block to work with. 


The BPT instruction generated as a result of fatal errors is in the 
RORMSA module of RMS-1l. The following is the state of the general 
registers at the time this instruction is issued: 


RO = RMS-11 error code 

Rl = Entry SP value 

R2 = Entry return PC 

R3 = Address of system impure area 


General registers Rl and R2 are always valid if the crash routine is 
invoked by a fatal user call error. When the crash routine is invoked 
by inconsistent internal conditions, the contents of general registers 
Rl and R2 may be meaningless if RMS-1l was executing an asynchronous 
RAB operation. 


The following subsections summarize, respectively, the fatal user call 
errors and the RMS-1ll1 inconsistent internal conditions that can cause 
invocation of the fatal error crash routine. 


A.3.1 Fatal User Call Errors 


When the fatal error crash routine is invoked because of a user call 
error, general register RO contains one of the following error codes: 


e ERSFAB 
e ERSRAB 


These error codes indicate that the user called RMS-1l using a control 
block that was not a valid FAB (for file operations such as SOPEN, 
SCREATE, etc) or RAB (for record operations such as S$CONNECT, SGET, 
$PUT, etc.). This condition can occur for any one of the following 
reasons: 
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l. The address of the FAB or RAB is 0. 
2. The address of the FAB or RAB is odd. 
3. The control block's BID field does not contain the _ proper 


block identifier code (i.e., FBSBID for FABs and RBSBID for 
RABs). 


A.3.2 RMS-11 Inconsistent Internal Conditions Errors 

When the crash routine is invoked because of RMS-1l inconsistent 
internal conditions, general register RO contains one of the following 
error codes: 


e ERSBUG 
e@ ERSMAP 


These error codes indicate internal problems with RMS-1l and are 
considered fatal. They can be caused by improper coding by the user 
(e.g., destroying some internal RMS-1ll1 data base), but are also _ used 
to detect RMS-1l bugs. When one of the above error codes is 
encountered, the user should provide, if possible, the following 
information to DEC with an SPR: 

1. The contents of the general registers. 


2. The first ten words, at a minimum, or all words upon the 
system stack. 


3. The operation the program was performing (e.g., S$OPEN, SGET, 
S$PUT). 


4. The organization of the file being processed. 
5. A load map of the task. 


6. If running on RSX-11M, a post-mortem dump. 
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PERFORMING BLOCK 1/0 


In addition to sequential, random, and RFA access, RMS-1l provides a 
fourth access mode known as block access. Block access allows you to 
bypass entirely the record processing capabilities of RMS-1l. Through 
Macros described in this appendix, you can directly read or write the 
virtual blocks of a file. 


NOTE 


Many elements of the internal structure 
of RMS-1l1 files are not normally visible 
to user programs. Through the use of 
block access, however, you can gain 
visibility of these elements. Extreme 
caution must be exercised, therefore, 
when altering the contents of the 
virtual blocks of an RMS-1ll-structured 
sequential, relative, or indexed file. 


B.1 SPECIFYING BLOCK ACCESS 


To use block access, you must allocate 1 buffer descriptor block (BDB) 
for each stream connected simultaneously for block access (RMS-1ll 
permits a single block access stream for sequential files and multiple 
Streams for relative and indexed files). These BDBs are specified in 
the PSBDB macro in the space pool declaration section (POOLSB .... 
POOLSE). At SOPEN or $CREATE time, the value FBSREA must be present 
in the FAC field of the FAB if the file will be read in block access 
mode and the value FBSWRT must be present in the FAC field if the file 
will be written in block access mode. If you are creating a file in 
block mode, the ORG field of the FAB must contain FBSSEQ and the RFM 
field must contain FBSUDF. Finally, a 512 byte buffer (either in’ the 
Space pool or ina user-specified location described by the BPA and 
BPS fields of the FAB) must be present for the SOPEN or $CREATE macro 
call to execute successfully. 


Once a file has been opened for block access, RMS-1l1 will not allow 
you to connect any streams to the file for record access. Only block 
access can be performed on the file. Each block access’ stream is 
activated by a  $CONNECT macro call and terminated by a $DISCONNECT 
macro call. 
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B.2 $READ - RETRIEVING VIRTUAL BLOCKS 


The SREAD macro retrieves a user-specified number of bytes from a file 
beginning on a_ specified virtual block boundary. You must supply a 
word-aligned work area (UBF) into which RMS-1l1l is to move the _ blocks 
of the file. You indicate the even number of bytes to be transferred 
to the UBF location in the USZ field and the starting virtual block 
number in the file in the BKT field. After completion of the 
transfer, RMS-1]1 uses the RBF and RSZ fields to describe the location 
and number of bytes actually transferred. 


The formats of the SREAD macro are as follows: 


1. label:$READ 


2. label:S$READ rab[,error[,success] ] 
where 

label is an optional user-defined symbol referring to 
the SREAD macro. 

rab is the address of a Record Access Block containing 
the specification of the block(s) to be retrieved. 

error is the address of a user completion routine to be 
called if the $READ operation fails. 

success is the address of a user completion routine to be 


called if the $READ operation succeeds. 


Table B-1 lists the fields of the Record Access Block used during’ the 
SREAD operation. 


Table B-l 
SREAD RAB Fields 


psec frsertpttom 


Bucket number. Must contain virtual block number 
of first block to be read. 


Internal stream identifier. 
User work area address (word-aligned). 


User work area size (must be an even number). 
This field will control the total amount of data 
transferred. Multiple virtual blocks’ can be 
retrieved from a disk file by specifying the 
appropriate multiple of 512 bytes in this field. 


Record address. This field is set equal to UBF. 


Record size. Actual number of bytes transferred 
(not including terminator character - refer to STV 
below). 


(Continued on next page) 
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Table B-1 (Cont.) 
-$READ RAB Fields 


pve fesertption 


Output Completion status code. Note that if this field 
(Cont. ) contains ERSEOF, the RSZ field will still describe 
a number of bytes transferred. 


Status value. After successful $READ operations 
from a unit record or terminal device, STV is used 
to report the terminating character for the input 
block. Refer to the S$GET operation in Section 
9.3.6.2 in Chapter 9. 


B.3 S$WRITE - WRITING VIRTUAL BLOCKS 
The SWRITE macro writes a user-specified number of bytes beginning on 
a specified block boundary to any of the RMS-1l file organizations. 
The user describes the blocks to be written in the RBF and RSZ fields. 
The BKT field must contain the virtual block number of the first block 
in the file to be written. 
The formats of the SWRITE macro are as follows: 

1. label:SWRITE 


2. label:SWRITE rab,[,error[,success] ] 


where 

label is an optional user-defined symbol referring to 
the SWRITE macro. 

rab is the address of a Record Access Block containing 
the specification of the block(s) to be written. 

error is the address of a user completion routine to be 
called if the SWRITE operation fails. 

success is the address of a user completion routine to be 


called if the SWRITE operation succeeds. 


Table B-2 lists the fields of the Record Access Block used during the 
SWRITE operation. 
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Table B-2 
SWRITE RAB Fields 


pve | besertetiom 


Bucket number. Must contain virtual block number 
of first block to be written. 


Internal stream identifier. 


Record address (word aligned). Address’ within 
user program of first byte of one or more blocks 
to be written. 


Record size (must be an even number). This field 
will control the total amount of data transferred. 
Multiple virtual blocks can be written to a disk 
file by specifying the appropriate multiple of 512 
bytes in this field. Partial blocks can be 
written but the contents of the unwritten portion 
of a block on disk are undefined. 


Completion status code. 


Status value. Actual number of bytes transferred. 


B.4 $SPACE - FORWARD AND BACKWARD SPACING OF MAGNETIC TAPE FILES 


When you open a file on magnetic tape in block mode, you can use the 
SSPACE macro call to space forward or backward in the file. RMS-1l 
returns an ERSIOP (illegal operation) if the file does not reside on 
Magnetic tape or has not been opened for block I/O. 


Table B-3 lists the fields of the Record Access Block used during’ the 
SSPACE operation. 


Table B-3 
SSPACE RAB Fields 


Bucket number. Only the low order 16 bits of this 
field are examined. RMS-11 interprets these bits 
aS representing a signed 15 bit integer. A 
positive integer represents the number of blocks 
the file is to be forward spaced. A negative 
integer represents the number of blocks the file 
is to be backspaced. 


Internal stream identifier. 


Record processing options. Can contain RBSASY. 


Output Completion status code. 
Status value. Number of blocks spaced. 
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MAGNETIC TAPE HANDLING 


The only form of magnetic tape structure supported by RMS-1ll is’ the 
Standard ANSI structure. This appendix describes the processing of 
Magnetic tape files and the ANSI labeling and _ structuring format 
supported by host operating systems. 


C.1 MAGNETIC TAPE FILE PROCESSING 


IAS and RSX-11M support the standard ANSI magnetic tape structure as 
described in the June 19, 1974 proposed revision to "Magnetic Tape 
Labels and File Structure’ for Information Interchange," ANSI 
X3.27-1969. Any of the following file/volume combinations can be 
used: 


1. Single file on a single volume, 

2. Single file on more than one volume, 

3. Multiple files on a single volume, 

4. Multiple files on more than one volume. 
Items 2 and 4 above constitute a volume set. 


The sequence in which volume and file labels are used and the format 
of each label type is defined in Sections C.2 and C.3. 


C.1.1 Access to Magnetic Tape Volumes 


Magnetic tape is a sequential access, single-directory storage medium. 
Only one user can have access to a given volume set at a time. No 
more than one file in a volume set can be open at ae time. Access 
protection is performed on a volume set basis. On volumes produced by 
DIGITAL systems, user access rights are determined by the contents of 
the owner identification field as described in Section C.2.1.1. 
Volumes produced by nonDIGITAL systems are restricted to read-only 
access unless explicitly overridden at MOUNT time. 


C.1.2 Rewinding Volume Sets 


A magnetic tape volume set can be rewound during a SOPEN, SCREATE, or 
SCLOSE macro call. Regardless of the method used to rewind the volume 
set, the following procedures are performed by the system: 
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1. All mounted volumes are rewound to BOT. 


2. If the first volume in the set is not mounted, the unit to be 
used is placed offline. 


3. If the volume is not already mounted and if the rewind was 
requested by a SOPEN or S$CREATE macro call, a request to 
mount the first volume is printed on the operator's console. 


4. If the rewind was requested by a SCLOSE macro call, no mount 
message is issued until the next volume is needed. 


C.1.3 Positioning to the Next File Position 

The FB$POS option in the file options (FOP) field of the FAB can be 
used to indicate that the file to be created is to be written 
immediately after the end of file labels of the most recently closed 
file. Any subsequent files in the volume set are lost. 

If the rewind-on-open option (FBS$RWO) also is specified, the file is 
created after the VOL1 label on the first volume of the set. All 
files that were previously contained in the volume set are lost. 

To create a file in the next file position, the FBSPOS option must be 
set in the FOP field. The default action of the file system is to 
position at the logical end of the volume set to create the file. 

When the default is used, no check is made for the existence of a file 


with the same name in the volume set. Therefore, a program written to 
use magnetic tape normally should specify FBSPOS. 


C.1.4 Single File Operations 
Single file operations are performed by specifying the FBS$RWO and 
FBSRWC options for the S$CREATE or SOPEN macro call. Using this 
approach, scratch tape operations can be performed as follows: 

1. Create the first file with rewind specified, 

2. Write the data records and close the file with rewind, 

3. Open the first file again for input, 

4. Read and process the data, 

5. Close the file with rewind, 

6. Create the second file with rewind specified, 


7. Write the data records, 


8. Close the file with rewind and perform any additional 
processing. 
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C.1.5 Multiple File Operations 

A multiple file volume is created by creating, writing, and then 
closing a_ series of files without specifying the FBSRWO option. The 
sequential processing of files on the volume can be accomplished by 
not specifying the FBSRWC (rewind-on-close) option when opening the 
files. 


Opening a file for extend (i.e., FB$PUT is specified in the FAC field 
of the FAB) is legal only for the last file on the volume set. 


The following tape operations are performed to create a multiple file 
tape volume: 


1. Create a file for output with rewind, 
2. Write data records and close the file, 
3. Create the next file with no rewind, 
4. Write the data records and close the file, 
5. Repeat for as many files as desired. 
Files on tape can be opened in a nonsequential order, but increased 


processing and tape positioning time is required. Nonsequential 
access of files in a multiple volume set is not recommended. 


C.2 VOLUME AND FILE LABELS 


Tables C-l, C-2, and C-3 present the format of volume labels and file 
header labels. 


C.2.1 Volume Label Format 


Table C-l 
Volume Label Format 


Character 
Position Field Name Contents 


Label identifier 


Label number 1 


Volume identifier Volume label. Any 
alphanumeric or special 
character in the center four 
columns of the ASCII code 
table. . 


(Continued on next page) 
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Table C-l1 (Cont.) 
Volume Label Format 


Character Length 
Position Field Name in Bytes Contents 


Accessibility Any alphanumeric or _ special 
character in the center four 
columns of the ASCII code 
table. A space indicates no 
restriction. All volumes 
produced by IAS or RSX-11 have 
a space in this position. 


Reserved Spaces 


Owner The contents of this field are 

identification system-dependent and are used 
for volume protection 
purposes. See Section C.2.1.1 
below. 


Reserved Spaces 


Label standard 1 
version 


C.2.1.1 Contents of Owner Identification Field - The owner 
identification field is divided into the following three subfields and 
a Single pad character: 

1. System identification (positions 38 through 40), 

2. Volume protection code (positions 41 through 44), 

3. UIC (positions 45 through 50), 


4. Pad character of one space (position 51). 


The system identification consists of the following character 
sequence. 


D%x 


x is the machine code and can be one of the following: 


8 - PDP-8 

A - DECsystem-10 
B - PDP-1ll 

F - PDP-15 


The D%x characters provide an identification method so that the 
remaining data in the owner identification field can be interpreted. 
In the case of tapes produced on PDP-1l systems, the system 
identification is D%B and the volume protection code and UIC are 
interpreted as described below. 


The volume protection code in positions 41 through 44 defines access 
protection for the volume for four classes of users. Each class of 
user has access privileges specified in one of the four columns as 
follows. 
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Position Class 


41 System (UIC no greater than [7,255]) 

42 Owner (group and member numbers match) 
43 Group (group number matches) 

44 World (any user not in one of the ee 


One of the following access codes can be specified for each character 
position. 


Code Privilege 


No access 

Read only 

Extend (append) access 
Read/extend access 
Total access 


Bm WD © 


The UIC is specified in character positions 45 through 50. The first 
three characters are the group code in decimal. The next three are 
the user code in decimal. 
The last character in the owner identification field is a space. 
The following is an example of the owner identification field. 
Owner identifier - D%B1410051102 
1. The file was created on a PDP-ll. 
2. System and group have read access. 
Owner has total access. 
All others are denied access. 


3. The UIC is [051,102]. 


C.2.2 User Volume Labels 


User volume labels never are written or passed back to the user. If 
present, they are skipped. 


C.2.3 File Header Labels 


The following information should be kept in mind when creating file 
header labels: 


e The Files-1ll naming convention uses a subset (Radix-50) of the 
available ANSI character set for file identifiers. 


@e One character in the file identifier, the period (.), is fixed 
by Files-ll. 


e A maximum of 13 of the 17 bytes in the file identifier are 
processed by Files-1ll. 


e It is strongly recommended that all file identifiers be 
limited to the Radix-50 PDP-11 character set and that no 
‘character other than the period (.) be used in the file type 
delimiter position for data interchange between PDP-1ll and 
DECsystem-10 systems. 
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nonDIGITAL systems, 
If they are 


e For data interchange between DIGITAL and 
the conventions listed above should be followed. 
not, refer to Section C.2.3.l. 


Tables C-2 and C-3 describe the HDR1 and HDR2 labels respectively. 


Table C-2 
File Header Label (HDR1) 


Character 
Position 


Length 


Field Name in Bytes 


Label identifier 
Label number 


File identifier 


File set 
identifier 


File section 
number 


File sequence 
number 

Generation number 
Generation version 


Creation date 


Expiration date 
Accessibility 
Block count 


System code 


Reserved 


1 


Any alphanumeric or _ special 
character in the center four. 
columns of the ASCII code 
table. 


Volume identifier of the first 
volume in the set of volumes. 


Numeric characters. This 
field starts at 0001 and is 
increased . by 1 for each 
additional volume used by the 
file. 


volume 
This 


File number within the 
set for this file. 
number starts at 0001. 
Numeric characters. 
Numeric characters. 


yyddd (with leading space) 


or 
00000 (with leading space) if 
no date. 


Same format as creation date. 
Space 

000000 

The three letters DEC followed 
by name of system that 
produced the volume. See 
Section C.2.1.1l. 


DECFILE11A 
DECSYSTEM10 


Examples: 


Pad name with spaces. 


Spaces 


(Continued on next page) 


Character 
Position 


MAGNETIC TAPE HANDLING 


File Hea 


Field Name 


Label identifier 
Label number 


Record format 


Block length 


Record length 


System-dependent 


information 


Buffer offset 


Reserved 


Table C-3 


der. Format (HDR2) 


- fixed length 

- variable length 

- spanned (not supported) 
- undefined 


Numeric characters 
Numeric characters 


Positions 16 through 36 are 
spaces. 


Position 37 defines carriage 
control and can contain one of 
the following: 


A - first byte of record 
contains FORTRAN 
control characters, 


space - line feed/carriage 
return is to be 
inserted between 
records, 


- the record contains 
all form control 
information. 


If DEC appears in positions 6] 
through 63 of HDR1, position 
37 must be as specified above. 


Positions 38 through 50 
contain spaces. 


Numeric characters. 00 on 

tapes produced by Files-1ll. 
Not supported on input to 
Files-ll. 


Spaces 
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C.2.3.1 File Identifier Processing by RMS-ll - The following steps 
describe the processing of a file identifier by RMS-1l. 


1. The first nine characters at a maximum are processed by an 
ASCII to Radix-50 converter. The filename scan continues 
until one of the following occurs: 


A conversion failure, 
9 characters are converted, 
A period (.) is encountered. 


2. If the period is encountered, the next three characters after 
the period are converted and treated as the file type. Ifa 
failure occurs or all nine characters are converted, the next 
character iS examined for a period. If it is a period, it is 
skipped and the next three characters are converted and 
treated as the file type. 


3. The version number is derived from the generation number’ and 
the generation version number as follows. 


(generation number — 1)*100 + generation version + 1 
At file output, the file identifier is handled as follows. 
1. The filename is placed in the first positions in the file 
identifier field. It can occupy up to nine positions. It is 


followed by a period. 


2. The file type of up to three characters is placed after the 
period. The remaining spaces are padded with spaces. 


3. The version number is then placed in the generation and 
generation version number fields as described in the 
following formulas. 


a. generation number = version # -1+H1 
100 


b. generation version # = version # - 1 
Modulo 
NOTE 
In both calculations, remainders are 
ignored. 
The following are examples. 


VERSION # GENERATION # GENERATION VER # 


1 1 0 
50 l 49 
100 1 99 
101 2 0 
1010 ll 9 
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C.2.4 End-of-Volume Labels 


End-of-volume labels are identical to the file header labels with the 
following exceptions: 


1. Character positions 1 through 4 contain EOV1 and EOV2 instead 
of HDR1 and HDR2, respectively. 


2. The block count field contains the number of records in the 
last file section on the volume. 


C.2.5 File Trailer Labels 


End-of-file labels (file trailer labels) are identical with file 
header labels with the following exceptions: 


1. Columns 1 through 4 contain EOF1 and EOF2 instead of HDR1 and 
HDR2, respectively, 


2. The block count contains the number of data blocks in the 
file. 


C.2.6 User File Labels 


User file labels never are written or passed back to the user. If 
present, they are skipped. 


C.3 FILE STRUCTURES 

The file structures illustrated below are the types of file and volume 
combinations that the file processor produces. Additional sequences 
can be read and processed by the file processor. 

If HDR2 is not present, the data type is assumed to be fixed (F) and 
the block size and record size are assumed to be the default value for 
the file processor. 512 decimal bytes is the default for both block 
and record size. The minimum block size and fixed length record size 
is 18 bytes. The maximum block size is 8192 bytes. 


The meaning of graphics used in the file structure illustrations is as 
follows. 


l. * indicates a tape mark, 
2. BOT indicates beginning of tape, 
3. EOT indicates end of tape, 


4. , indicates the physical record delimiter. 


C.3.1 Single File Single Volume 


BOT, VOL1 ,HDR1,HDR2* ---DATA---*EOF 1 , EOF 2** 
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C.3.2 Single File Multi-Volume 


BOT, VOL1 ,HDR1,HDR2*---DATA---*EOV1 , EOV2** 
BOT, VOL1 ,HDR1,HDR2*---DATA---*EOF1 , EOF2** 


C.3.3 Multi-File Single Volume 


BOT, VOL1,HDR1,HDR2* ---DATA---~*EOF1,EOF 2*HDR1,HDR2*--~DATA--—*EOF1,EOF2** 


C.3.4 Multi-File Multi-Volume 


BOT, VOL1,HDR1,HDR2* --DATA~-—* EOF 1, EOF 2*HDR1 , HDR2* -—-DATA--*EOV1 , EOV2** 
BOT, VOL1,HDR1,HDR2* --DATA--—* EOF 1, EOF 2*HDR1 , HDR2*-~DATA-~*EOF1 , EOF 2** 


C.4 END OF TAPE HANDLING 


End of tape is handled automatically by the magnetic tape file 
processor. Files are continued on the next volume providing the 
volume is already mounted or mounted upon request. A request for’ the 
next volume is printed on CO. 


C.5 ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS COMPATIBLE) 


Figure C-1 illustrates the format of a file header block that is 
returned by the file header READ ATTRIBUTE command for ANSI magnetic 
tape. The header block is constructed by the magnetic tape primitive 
from data within the tape labels. 


MAGNETIC TAPE HANDLING 


ANSI MAGTAPE FCS-COMPATIBLE FILE 
HEADER BLOCK 


MAP OFFSET H. IDOF 
H.MPOF 


H.FNUM 
H.FSEQ 
H.FLEV 
- FOWN=H.. PROG 


H.FPRO 


HEADER 7 
AREA RECORD ATTRIBUTES | RECORD TYPE CODE H.UFAT 
RECORD SIZE IN BYTES 


N WORDS OF ZERO'S 


X+I.FNAM 
FILE NAME RAD50 (IDENT OFFSET *2) =x 
I.FTYP 
FILE TYPE RAD50 


como 
FICATION 


AREA PAD BYTE OF 0 X+47. 
COPY OF THE X+50. 
HDR1 LABEL 
COPY OF THE X+130. 
HDR2 LABEL 
(if byte 1 of label = 0, 
label is not present) 
MAP NULL MAP, I.E., ZERO'S X+210.= 
AREA (10 BYTES LONG) (MAP OF OFFSET 2) 


Figure C-1l 
ANSI Magnetic Tape File Header Block 
(FCS Compatible) 


APPENDIX D 
FORMULAS 


This appendix contains formulas that can be used to calculate the 
following: 


l. 


2. 


36 


Number 


Number 
files. 


. Number 


of records per block in sequential files. 


of user data records per bucket in relative or indexed 


of entries per bucket in the index levels of all 


indexes and the data level of alternate indexes in an indexed 


file. 


D.1 SEQUENTIAL FILES - AVERAGE RECORDS PER BLOCK 


Fixed 


VFC 


Record Format Magnetic Tape 


Variable 


Table D-1 
Average Records Per Block 
in Sequential Files 


Sequential File Medium 


512 
recsz 


BLS 
recsz 


512 
(recsz+2) 


BLS 
(recsz+4) 


512 BLS 
(recsz+FSZ+2) (recsz+FS2Z+4) 


* Records in a sequential file on disk are word-aligned. 


where 


recSz 


is the actual record size (for fixed format) or 
average record size (for variable or VFC) in 
bytes. 


FORMULAS 


BLS is the magnetic tape block size asi specified in 
the BLS field of the FAB at the time the file was 
created. 

FSZ is the fixed control area size as specified in the 
FSZ field of the FAB at the time the file was 
created. 


D.2 RELATIVE AND INDEXED FILES - AVERAGE DATA RECORDS PER BUCKET 


Table D-2 
Average User Data Records 
per Bucket 


File Organization 


Indexed 
_ Relative (data level of primary index) 


_ __DBKT (DBKT-15) 
(recsz+1) (recsz+7) 


Record Format 


DBKT (DBKT-15) 
(recsz+3) (recsz+9) 


DBKT 
(recsz+FSZ+3) 


where 
DBKT | is the bucket size in bytes (a multiple of 512). 
recsZ is: 
1. The actual record size for fixed format 
records. 
2. The maximum record size for variable or VFC 
format records in relative files. 
3. The average record size for variable format 
records in indexed files. 
FSZ is the fixed control area size as specified in the 
FSZ field of the FAB at the time the file was 
created. 


FORMULAS 


D.3 INDEXED-FILES - AVERAGE ENTRIES PER INDEX AND ALTERNATE KEY 
DATA LEVEL 


Table D-3 
Average Entries Per Index and Alternate 
Key Data Level Bucket 


Bucket Type 


Index Level Data Level Data Level 
(primary and (alternate key -no | (alternate key - 
alternate duplicates allowed) | duplicates allowed 


(IBKT-15) (DBKT-15) (DBKT-15) 
(keysz2+3) (keysz+9) (keysz+8+ (5*dups) ) 


IBKT is the size in bytes of buckets in the index level 
(a multiple of 512). 

DBKT is the size in bytes of buckets in the data level 
of the alternate key index (a multiple of 512). 

keysz is the key size in bytes. 

dups is the number of records with identical values for 


a particular instance of a key value. 


3,9,5 are average values representing actual ranges of, 
respectively, 2 to 4, 8 to 10, and 4 to 6. 


APPENDIX E 


SAMPLE CODE SEGMENTS 


The sample code segments in this appendix demonstrate the copying 
records from an existing sequential file to a new sequential file. 


; DEMO.RMS 


; PROGRAM TO COPY RECORDS FROM A SEQUENTIAL FILE NAMED 
; FILE1.DAT TO A NEW SEQUENTIAL FILE NAMED FILE2.DAT 


; STEP 


STEP 


=e 


FABI1: 


NAME1: 


FAB2: 


NAME 2: 


1: ACCESS THE NECESSARY RMS MACROS 


-MCALL SINIT,ORGS$,FABSB,RABSB, POOLSB, $CREATE, SOPEN, $CLOSE 
-MCALL S$CONNECT,$GET,SPUT,SFETCH , SSTORE, SCOMPARE 


2: DEFINE CONTROL BLOCKS AND FILE NAME STRINGS 


:;THE FAB FOR THE INPUT FILE, WHICH ALREADY EXISTS, WILL BE 
;FILLED WITH MOST OF THE ESSENTIAL INFORMATION CONCERNING 
;FILE1.DAT WHEN THE FILE IS OPENED. THE PROGRAM NEED ONLY 
SPECIFY ENOUGH INFORMATION TO OPEN THE FILE. 


FABSB 
FSFNA 
FSFNS 
FSLCH 
FABSE 


eASCII /FILE1.DAT/ 


NAME1 
9 


1 


7FAB FOR FILE1.DAT 

ADDRESS OF NAME STRING 
STRING IS 9 CHARACTERS LONG 
;ACCESS ON CHANNEL 1 

7;END OF FAB1 


;NAME STRING FOR FAB1 


;HERE, AND WITH FILE2, WE ASSUME THAT THE FILE EXISTS 
;ON THE SYSTEM DISK UNDER THE ACCOUNT ON WHICH WE ARE 
LOGGED IN. 


- EVEN 


;THE FAB FOR THE OUTPUT FILE, WHICH DOES NOT YET EXIST, MUST 


; (CONTROL BLOCKS MUST BE WORD ALIGNED) 


of 


;BE FILLED WITH THE INFORMATION NECESSARY TO CREATE IT (AS IN 
7;THE PREVIOUS CASE, SOME FIELDS SIMPLY CONTAIN DEFAULT VALUES 


7AND ARE NOT EXPRESSED EXPLICITLY). SOME OF THIS INFORMATION 


;WILL DEPEND ON THE CHARACTERISTICS OF FILE1.DAT, AND MUST BE 
;FILLED IN AT RUN-TIME AFTER FILE1.DAT HAS BEEN OPENED. 


FABSB 
FSFNA 
FSFNS 
FSLCH 
FSFAC 
FABSE 


-ASCII 


NAME 2 
9 

2 
FBSPUT 


/PILE2.DAT/ 


7;FAB FOR FILE2.DAT 

ADDRESS OF NAME STRING 
;STRING IS 9 CHARACTERS LONG 
ACCESS ON CHANNEL 2 

;WRITE ACCESS REQUIRED 

7;END OF FAB2 


;NAME STRING FOR FAB2 


E-1 


SAMPLE CODE SEGMENTS 


- EVEN 

RAB1: RABSB ;RAB FOR FILE1.DAT 
RSFAB FAB1 ;ADDRESS OF OWNER (FAB) 
RSRAC RBSSEQ ;SPECIFY SEQUENTIAL ACCESS 
RSUBF RECBUF ;ADDRESS OF RECORD BUFFER FOR $GETS 
RSUSZ 500 ;SIZE OF THIS BUFFER (500. BYTES) 
RS$RHB HEDBUF ;ADDRESS OF RECORD HEADER BUFFER 

; (NECESSARY FOR VFC RECORDS ONLY) 

RABSE ;END OF RABI 

RAB 2: RABSB ;RAB FOR FILE2.DAT 
RSFAB FAB2 ;ADDRESS OF OWNER 
RS$RAC RBSSEQ ;SPECIFY SEQUENTIAL ACCESS 
RSRBF RECBUF ;ADDRESS OF RECORD BUFFER FOR $PUTS 
RSRSZ 500 ;SIZE OF THIS BUFFER (500. BYTES) 
RSRHB HEDBUF ;ADDRESS OF RECORD HEADER BUFFER 

; (NECESSARY FOR VFC RECORDS ONLY) 

RABSE 7;END OF RAB2 

; STEP 3: ALLOCATE THE BUFFERS SPECIFIED ABOVE 

RECBUF: .BLKW 250. 

HEDBUF: .BLKW 128. 


; STEP 4: GENERATE RMS INTERNAL SPACE POOL 


POOLSB ; BEGIN POOL SPECIFICATION 
PSFAB 2 ;A FAB FOR EACH FILE 
PSRAB 2 ;A RAB FOR EACH FAB 
PSBDB 2 7;AN I/O BUFFER FOR EACH RAB 
PSBUF 1024 ;MINIMUM BUFFER SIZE IS 512. BYTES 
POOLSE 7;END OF POOL SPECIFICATION 
; STEP 5: DEFINE THE RMS FUNCTIONALITY REQUIRED 
ORGS SEQ, <CRE, GET, PUT> ;SEQUENTIAL FILES ONLY, S$FIND, 
;SUPDATE, SDELETE NOT REQUIRED 
STEP 6: PROVIDE A GENERAL ERROR ROUTINE TO HANDLE UNEXPECTED ERRORS 


WHICH MIGHT OCCUR (WHAT IF FILE1.DAT DID NOT EXIST, OR CON- 
TAINED A RECORD LARGER THAN 500 BYTES?). THIS IS AN ALTER- 
NATIVE TO THE ‘COMPLETION ROUTINE' FUNCTION PROVIDED BY RMS. 


=e =e we SEO 


ERROR: ;(CODE WHICH WILL HANDLE THE ERROR, PROMPT AT THE TERMINAL FOR 
;FURTHER INSTRUCTIONS, ETC.) 
; STEP 7: WRITE THE PROGRAM 
START: SINIT ; INITIALIZE RMS. 
SOPEN #FAB1 ;OPEN FILE1.DAT, 
MOV #FAB1,RO ;SET UP FOR $COMPARE: 
SCOMPARE #0,STS,RO ;NEGATIVE STS VALUE IMPLIES OPEN FAILURE 
BLT 1$ 7;BRANCH IF SUCCESSFUL 
JSR PC ,ERROR ;OTHERWISE EXECUTE ERROR ROUTINE. 
1$; MOV #FAB2,R1 ;COMPLETE INITIALIZATION OF FAB2: 
SFETCH R2,RAT,RO 7;GET RAT FIELD FROM FABI 
SSTORE R2,RAT,R1 AND MOVE IT INTO FAB2; 
SFETCH R2,RFM,RO 7;DO THE SAME WITH THE RFM FIELD; 
SSTORE R2,RFM,R1 
SFETCH R2,FSZ,RO 7FSZ IS PERTINENT ONLY IF FILE1.DAT 
SSTORE R2,FSZ,R1 ;MAY CONTAIN VFC RECORDS. 
SFETCH R2,MRN,RO 7YOU MAY OR MAY NOT WISH TO TRANSFER 


E-2 


SAMPLE CODE SEGMENTS 


SSTORE R2,MRN,R1 7;MRN, MRS, AND FOP. IF MRN IS COPIED, 
SFETCH R2,MRS,RO 7REMEMBER THAT IT IS A 2-WORD FIELD, 
SSTORE R2,MRS,R1 ;AND WILL DESTROY THE CONTENTS OF R3. 


; INITIALIZATION OF FAB2 SHOULD NOW BE COMPLETE EXCEPT FOR ANY 
SPECIAL CASES (FOR EXAMPLE, IF FILE2.DAT IS ON MAGNETIC TAPE, 
7YOU MAY WISH TO SET THE BLS FIELD). 


SFETCH R2,ALQ,RO 
SSTORE R2,ALQ,R1 


SCREATE R1 ;NOW CREATE FILE2.DAT (R1=FAB2) : 

SCOMPARE #0,STS,R1 7;CHECK FOR FAILURE , 

BLT 2$ ;BRANCH IF SUCCESSFUL 

JSR PC, EKROR ;OTHERWISE EXECUTE ERROR ROUTINE. 
28: MOV #RAB1,RO CONNECT THE RABS. 

MOV #RAB2,R1 


SCONNECT RO 
SCOMPARE #0,STS,RO 


BLT 3$ 7;BRANCH IF SUCCESSFUL 
JSR PC,ERROR 
3$: SCONNECT Rl 
SCOMPARE #0,STS,R1 
BLT 4S 
JSR PC, ERROR 
4S: $GET RO ;GET A RECORD FROM FILE1.DAT. 
SCOMPARE #ERSEOF,STS,RO 7;WERE WE AT END-OF~FILE? 
BEQ DONE ;IF SO, CLEAN UP AND EXIT. 
SCOMPARE #0,STS,RO 7;SOME OTHER ERROR? 
BLT 5$ ;BRANCH IF SUCCESSFUL 
JSR PC,ERROR 7IF SO, HANDLE IT. 
5S: SFETCH R2,RSZ,RO COPY RECORD LENGTH FROM 
SSTORE R2,RSZ,R1 ;RAB1 TO RAB2. 
$PUT Rl ;OUTPUT THE RECORD TO FILE2.DAT. 
SCOMPARE #0,STS,R1 
BLT 6$ 7;BRANCH IF SUCCESSFUL 
JSR PC,ERROR 
6$: BR 4S 7;LOOP UNTIL DONE. 
DONE : MOV #FAB1,RO ;BACK TO THE FABS FOR S$CLOSE. 
MOV #FAB2,R1 
$CLOSE RO 
SCOMPARE #0,STS,RO 
BLT 1$ ;BRANCH IF SUCCESSFUL 
JSR PC,ERROR 
1$: S$CLOSE Rl 
SCOMPARE #0,STS,R1 
BLT 2$ 
JSR PC , ERROR 


283: 
>RMS IS NOW DONE: FILE2.DAT NOW CONTAINS ALL THE DATA RECORDS 
;OF FILE]1.DAT, PLUS WHATEVER OTHER INFORMATION (MRS, MRN, ETC.) 
;YOU CHOSE TO DUPLICATE. INSERT YOUR OWN EXIT CODE AND EXIT. 


- END START 


APPENDIX F 


ASSEMBLING AND TASK BUILDING 


When you assemble a program that uses RMS-1ll1 facilities, you must 
reference the following file as a macro library in your command line: 


[1,1] RMSMAC.MLB 
When you task build without RMS-11 overlays, you must include in the 
task builder command line or user ODL root statement a reference to 
the following file as an object library: 

[1,1]RMSLIB.OLB 

When you task build with RMS-11 overlays, you must: 

l. Edit a private copy of the RMS-1l prototype ODL to _ include 
the needed portions of RMS-1ll. The prototype ODL is in the 
following file: 

{1,1]RMS11.ODL 


2. Include references in the root statement of your ODL to the 
following factors: 


a. RMSROT 
b. RMSALL 


RMSALL can be referenced as a co-tree. If RMSALL is a 
co-tree, you must specify the full search option to the task 
builder. 


3. Reference, in your overlay description language, your private 
copy of the edited RMS11.ODL as an indirect file. 


Access mode, specifying an, 9-28 


AID, 7-21 

Allocation XAB, 7-19 

ALN, 7-21 

ALQ, 5-6, 7-22 

AOP, 7-23 

Asynchronous record operations, 
9-26 


BPS, 5-11 

Bucket locking, 9-21, 9-22 

Bucket size, 5-7 to 5=9, 7=24 

Buffer descriptor blocks, 3-6 

Buffers, I/O, 3-4, 3-9, 3-10, 
5-10, 5-11 


Calling sequence, RMS-11, 9-3 
CDT, 7-3 
Centralized space pool, 3-4 
SCLOSE, 9-16 
COD, 7-2 
SCOMPARE, 4-2 
Completion routines, 9-3 to 9-5 
Completion status code, 5-27, 
6-15, 9-6 
SCONNECT, 2-7, 9-18, 9-25, 9-26 
Context of record operations, 
9-23 
Control block fields, 
accessing at runtime, 4-1 to 
4-5 
numeric values in 2=-word, 4-2 
offsets of, 4-2 
usage, 9=5 
Control blocks, user 
accessing fields in, 4-1 to 
4-8 
function of, 2-3 
FAB, 2-4 
NAM, 2-5 
RAB, 2-4 
XAB, 2-5 
S$CREATE, 9-7 
CTX, 5-12, 6-4 
Current context of record 
operations, 9-23 
Current Record, 9-23, 9-25 


INDEX 


DAN, 7-5 
Date and Time XAB, 7-3 
Declaring RMS-1l facilities, 
S$INIT, 3-10, 3-11 
SINITIF, 3-10, 3-11 
-MCALL directive, 3~1, 3-2 
ORGS, 3-3, 3-4 
space pool requirements, 3-4 
to 3-10 
S$DELETE, 9-25, 9-26, 9-28, 9-40 
DEQ, 5-13, 7-24 
DEV, 5-14 
Device characteristics, 5-14 
DFL, 7-6 
S$DISCONNECT, 9-19 
SDISPLAY, 9-12 
DNA, 5-14 
DNS, 5-15 


ERSRTB, 9-24, 9-25, 9-29, 9-30 

SERASE, 9-13 

ESA, 8=-2 

ESL, 8=3 

ESS, 8-3 

SEXTEND, 9-14 

Extended Attribute Blocks, 
allocating, 7-1, 7-2 
Allocation, 7-19 
Date and Time, 7-3 
existing files and, 2-6 
file operations and, 2-5, 2-6 
File Protection Specification, 

7-16 

Key Definition, 7-4 
linking, 7-2 
new files and, 2-6 
order of, 7=2 
Summary, 7-26 
types of, 7-1 


FSALQ, 5-7 

FSBKS, 5-9 

FSBLS, 5-10 
FSBPA, 5-10 
FSBPS, 5-11 
FSCTX, 5-12 
FSDEQ, 5-13 
FSDNA, 5-14 
FS$DNS, 5-15 
FSFAC, 5-16 
FSFNA, 5-17 
FSFNS, 5-18 


Index-1 


Sequential access mode, 


9-28 


INDEX (CONT.) 


yay 


Sequential file organization, 


SFIND and the, 9-3 
SGET and the, 9-35 
SPUT and the, 9-37 
specifying, 5-24 
SUPDATE and the, 9 
Sharing, file 


2 


-39 


bucket locking and, 9-21 
file organizations and, 9-20 


program information, 9-20 


record operations and, 9-20 


specifying, 5-26 
SHR, 5-26, 9-20, 9-2 
SIZ, 4-3, 4-4, 4-6, 
Space pool, 

buffers in, 3-4 

centralized, 3-4 


1 


427, 7=15 


declaration, 3-5 to 3-9 


SSTORE, 4-6 


Stream record format, 5-22, 


STS, 5-27, 6-15, 9-6 
Summary XAB, 7-26 


5-25 


Synchronous record operations, 


9-26 


STESTBITS, 4-7 


STRUNCATE, 9-25, 9-26, 9-42 


9-30, 9-38 to 9= 


User control blocks, 


accessing fields in, 


function of, 2-3 
FAB, 2-4 
NAM, 2-5 
RAB, 2-4 
XAB, 2-5 
USZ, 6-16, 9-29 


Variable format records 

VFC format records, 5-: 
5-26, 6-12 

VOL, 7-26 


XSAID, 7-21 
XSALN, 7-21 
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X$SIZ, 7-15 

XAB (the FAB field), 5: 

XAB (Extended Attribut 
allocating, 7-1, 7-2 
Allocation, 7-19 
Date and Time, 7-3 
existing files and, 
file operations and, 


9-28, 9-29, File Protection Spec. 
40 7-16 
Key Definition, 7-4 
4-1 to 4-8 linking, 7-2 


new files and, 2-6 
order of, 7-2 
Summary, 7-26 
types of, 7-1 
XABSB, 7-1 
XABSE, 7-2 
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READER'S COMMENTS 


NOTE: This form is for document comments only. DIGITAL will 
use comments submitted on this form at the company's 
discretion. Problems with software should be reported 
on a Software Performance Report (SPR) form. If you 
require a written reply and are eligible to receive 
one under SPR service, submit your comments on an SPR 
form. 


Did you find errors in this manual? If so, specify by page. 


Did you find this manual understandable, usable, and well-organized? 
Please make suggestions for improvement. 


Is there sufficient documentation on associated system programs 
required for use of the software described in this manual? If not, 
what material is missing and where should it be placed? 


Please indicate the type of user/reader that you most nearly represent. 
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User with little programming experience 
Student programmer 
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